.env.example

# ACP runtime environment
#
# This file is both the local template and the drift-checked manifest of
# environment variables read by the host, CLI, stdio bridge, and dogfood scripts.
# Values below mirror local-development defaults unless the variable is only
# meaningful when a feature is enabled.

ACP_PORT=4317
ACP_LOG_LEVEL=info
ACP_REQUIRE_AUTH=false
ACP_REQUIRE_WORKSPACE_BINDINGS=false

# Session issuance
#
# trusted-client preserves the caller-derived local bootstrap. static verifies
# an Authorization bearer credential by SHA-256 digest and derives worker,
# permissions, and workspace bindings from ACP_SESSION_ISSUANCE_POLICY. The
# hosted profile defaults to static and fails startup without a valid policy.
# Keep credential preimages outside this file; only digests belong in policy.

ACP_SESSION_ISSUER=trusted-client
ACP_SESSION_ISSUANCE_POLICY=

# Deployment profile (optional)
#
# A one-variable preset over the knobs below. Explicit ACP_* variables override
# ordinary profile defaults; hosted security requirements cannot be weakened.
# Supported profiles: `local` (memory storage,
# no auth), `single-node` (sqlite storage, auth on), `hosted` (postgres,
# pg-notify, auth on, workspace-bound sessions), and `self-host-ha` (postgres,
# pg-notify, auth on, workspace-bound sessions). Leave unset for `local`
# behavior.

ACP_PROFILE=local

# Storage
#
# memory keeps state in process and is the default. Use sqlite when ACP should
# preserve workspaces, work units, leases, checkpoints, artifacts, memory,
# reviews, and event history across restarts.

ACP_STORAGE_ADAPTER=memory
ACP_SQLITE_PATH=acp.sqlite

# Event fan-out
#
# in-process is the default single-node broker. pg-notify uses Postgres
# LISTEN/NOTIFY so live event subscribers on different replicas receive the same
# persisted events; set ACP_DATABASE_URL when enabling it.

ACP_EVENT_BROKER=in-process

# postgres adapter: network-durable / multi-replica storage. Set
# ACP_STORAGE_ADAPTER=postgres and provide a standard connection string here;
# the host fails fast at boot if it is unset. Leave empty otherwise.
ACP_DATABASE_URL=

# Runtime policy
#
# Effect duration values use readable units such as "15 minutes",
# "60 seconds", and "1 hour".

ACP_DEFAULT_LEASE_TTL="15 minutes"
ACP_EVENT_RETENTION_DAYS=30
# Maximum spawn-graph depth for work units. A root is depth 0, so 10 allows a
# delegation chain of eleven units. Creating a child beyond this fails with 400.
ACP_MAX_WORK_DEPTH=10
# Path to a JSON resource-access policy. Unset means no policy engine and
# unchanged behaviour. A malformed or self-inconsistent policy aborts startup.
ACP_POLICY_FILE=
# Path to a JSON webhook-hook document (ADR-0022). Unset means no webhook
# hooks. Endpoints must be https, and any failure — unreachable, slow, or an
# undecodable verdict — refuses the mutation rather than letting it through.
ACP_HOOKS_FILE=
# Directory of per-workspace policy overlays named <workspace_id>.json. An
# overlay may add denials the host policy lacks, but can never turn a host
# denial into an allow — otherwise handing one to a workspace owner would be a
# privilege-escalation path.
ACP_POLICY_OVERLAY_DIR=
# Agent sandbox runtime (ADR-0026). `none` provisions nothing and leaves
# behaviour unchanged; `docker` runs each work unit's agent in a container whose
# only writable paths are the ones that work unit holds leases on.
# Require Ed25519 signatures on state-changing worker claims (ADR-0024). Off by
# default so unsigned workers stay first-class; a failed signature is refused in
# either mode, since enforcement governs whether proof is required, not whether
# a failed proof is acceptable.
ACP_REQUIRE_WORKER_SIGNATURES=false
# How long a worker registration stays live without a heartbeat. A lapsed
# worker becomes `offline` with `expires_at` in the past; the row survives so
# events attributing work to it keep resolving.
ACP_WORKER_REGISTRATION_TTL="24 hours"
ACP_SANDBOX_ADAPTER=none
ACP_SANDBOX_IMAGE=
# Hardened OCI runtime for the docker adapter. Unset uses the daemon default
# (runc), which shares the host kernel — fine for first-party agents, not a
# boundary for hostile code. Set `runsc` for gVisor or `kata` for microVMs.
ACP_SANDBOX_RUNTIME=
# Absolute path of the workspace on the host. Required by the docker adapter:
# it is the read-only root, and the boundary leased paths must sit inside.
ACP_WORKSPACE_ROOT=
ACP_MAX_ARTIFACT_SIZE_MB=16
ACP_SSE_HEARTBEAT="15 seconds"
ACP_SESSION_TTL="1 hour"
ACP_SWEEP_INTERVAL="60 seconds"

# Observability
#
# ACP_METRICS_TOKEN both enables and guards the Prometheus scrape endpoint at
# GET /metrics. Unset (the default), the endpoint answers 404; set, a scrape must
# present it as `Authorization: Bearer <token>`. Keep it empty in committed files
# and inject it from the operator shell or process supervisor.

ACP_METRICS_TOKEN=

# Clients and stdio bridge
#
# ACP_BASE_URL points clients at an already-running ACP host. ACP_RPC_TOKEN is a
# bearer issuance credential during static `session init`, then the returned
# bearer session id for later calls. Keep it empty in committed files and inject
# it from the operator shell or process supervisor.

ACP_BASE_URL=http://localhost:4317
ACP_RPC_TOKEN=

# Dogfood smoke metadata
#
# These are optional and only read by scripts under scripts/. ACP_DOGFOOD_RUN_ID
# gives a run a stable correlation key, ACP_DOGFOOD_WORKER_ID overrides the
# single-worker smoke identity, ACP_DOGFOOD_WORKSPACE_ID binds dogfood sessions
# to an existing workspace for hosted policy tests, and ACP_DOGFOOD_PR_URL
# attaches a real pull request artifact to the smoke run.

ACP_DOGFOOD_RUN_ID=
ACP_DOGFOOD_WORKER_ID=agent_codex_dogfood
ACP_DOGFOOD_WORKSPACE_ID=
ACP_DOGFOOD_PR_URL=

# Docker dogfood controls
#
# ACP_DOCKER_IMAGE and ACP_DOCKER_CONTAINER override the temporary image and
# container names used by `npm run dogfood:docker-cli`. ACP_DOCKER_HA_KEEP_STACK
# keeps the Compose HA stack and Postgres volume after
# `npm run dogfood:docker-ha`, which is useful for manual inspection.

ACP_DOCKER_IMAGE=acp:docker-cli-dogfood
ACP_DOCKER_CONTAINER=
ACP_DOCKER_HA_KEEP_STACK=false