Environment variable reference¶

AWC reads configuration from environment variables. This page lists every AWC_* variable the current build reads, the binary that reads it, the default, and the effect. Values come from the code, not from memory. Where the code and the spec disagree, the code wins and the disagreement is noted.

Two non-AWC_ variables are required peers and are listed at the end: DATABASE_URL and AWCD_SOCKET.

Nested config convention (awcd only)¶

awcd loads a layered config (file, then environment, then flags). The environment layer reads flat fields as AWC_<FIELD> and nested fields as AWC_<SECTION>__<FIELD>. The double underscore separates a config section from a field.

Field path	Environment variable
`host_id`	`AWC_HOST_ID`
`control_plane_endpoint`	`AWC_CONTROL_PLANE_ENDPOINT`
`cache.max_bytes`	`AWC_CACHE__MAX_BYTES`
`leases.expiry_seconds`	`AWC_LEASES__EXPIRY_SECONDS`

Field names map from snake_case to SCREAMING_SNAKE_CASE. allowed_bind_roots is a comma-separated list. Integer fields must parse as non-negative integers, or startup fails with a ParseValue error.

Only awcd reads this structured layer. awc-control and awc-worker read their own direct variables (see the tables below).

Structured config variables (awcd)¶

Read by awcd from the structured environment layer. Layer order is file, then environment, then flags; later layers override earlier ones.

Top-level fields¶

Variable	Type	Default	Effect
`AWC_HOST_ID`	string	none, required	Local host identifier, `host_<ulid>`. Startup fails if unset or malformed.
`AWC_CONTROL_PLANE_ENDPOINT`	URL	none, required	Control plane URL. Schemes `http` and `https` only.
`AWC_BASEFS_MOUNT`	absolute path	none, required	Internal mount point for the read-only base filesystem.
`AWC_CACHE_ROOT`	absolute path	none, required	Root directory of the local content cache.
`AWC_WORKSPACE_ROOT`	absolute path	none, required	Root directory for per-workspace merged mounts.
`AWC_ALLOWED_BIND_ROOTS`	comma-separated paths	empty list	Host paths that may be bind targets. Each path must be absolute.
`AWC_HEALTH_HTTP_LISTEN`	`host:port`	unset (HTTP server disabled)	Loopback address for the liveness, readiness, and metrics HTTP server.

The three roots (basefs_mount, cache_root, workspace_root) must be distinct. Startup rejects any pair that is equal.

Cache limits¶

Default to the built-in cache defaults when unset.

Variable	Type	Default	Effect
`AWC_CACHE__MAX_BYTES`	`u64`	`1000000000000` (1 TiB)	Total byte limit of the local cache. Must be greater than zero.
`AWC_CACHE__MIN_FREE_BYTES`	`u64`	`50000000000` (50 GiB)	Minimum free space to preserve on the host filesystem.
`AWC_CACHE__MAX_REMOTE_FETCHES`	`u32`	`128`	Bounded object-store read concurrency.
`AWC_CACHE__MAX_REMOTE_FETCHES_PER_TENANT`	`u32`	`32`	Per-tenant object-store read concurrency. Cannot exceed the global limit.
`AWC_CACHE__MAX_PREFETCH_FETCHES`	`u32`	`8`	Prefetch concurrency. Cannot exceed the global limit.

Checkpoint limits¶

Default to the built-in checkpoint defaults when unset.

Variable	Type	Default	Effect
`AWC_CHECKPOINT__MAX_CONCURRENT`	`u32`	`4`	Maximum concurrent checkpoint uploads. Must be greater than zero.
`AWC_CHECKPOINT__FREEZE_TIMEOUT_SECONDS`	`u64`	`10`	Freeze and quiesce timeout for cutting a checkpoint, in seconds. Must be greater than zero.
`AWC_CHECKPOINT__PRESERVE_LOCAL_GRACE_SECONDS`	`u64`	`3600`	Grace period for preserving local changes after a checkpoint, in seconds. Must be greater than zero.

Lease timing¶

Default to the built-in lease defaults when unset.

Variable	Type	Default	Effect
`AWC_LEASES__RENEW_INTERVAL_SECONDS`	`u64`	`30`	How often the holder renews the lease, in seconds. Must be less than `expiry_seconds`.
`AWC_LEASES__EXPIRY_SECONDS`	`u64`	`90`	Lease lifetime before automatic expiry, in seconds.
`AWC_LEASES__DISCONNECTED_GRACE_SECONDS`	`u64`	`60`	Grace period for a disconnected holder before revocation, in seconds. Must be greater than zero.

Object store selection¶

AWC_CAS_URL selects the backing object store. Read by awcd, awc-control, and awc-worker.

Variable	Type	Default	Effect
`AWC_CAS_URL`	URL string	`memory://` (`awcd`, `awc-control`); required, no default (`awc-worker`)	Object store transport. `memory://` is the in-process store. `s3://` selects the S3-compatible transport and requires the `s3` feature plus the `AWC_S3_*` variables. Any other scheme is a startup error.

S3 transport variables¶

Read when AWC_CAS_URL is s3://. The s3 feature must be enabled.

Variable	Type	Default	Effect
`AWC_S3_ENDPOINT`	URL string	none, required	S3-compatible endpoint URL. Must be `https://` unless `AWC_S3_ALLOW_HTTP=1`.
`AWC_S3_BUCKET`	string	none, required	Bucket name. A path suffix after the bucket becomes the key prefix.
`AWC_S3_REGION`	string	`us-east-1`	SigV4 signing region. B2 encodes it in the endpoint host (e.g. `eu-central-003`).
`AWC_S3_KEY_PREFIX`	string	empty	Key prefix applied to every object (normalized to end with `/`). Required when the credentials are restricted to a prefix, e.g. a B2 namePrefix-scoped key.
`AWC_S3_ALLOW_HTTP`	`0`/`1`	`0`	Explicit opt-in for plaintext `http://` endpoints (cluster-local MinIO in dev, CI, and the Helm chart default). Any other value is ignored.
`AWC_S3_CONDITIONAL_CREATE`	`0`/`1`	endpoint-dependent	`1` sends `If-None-Match: ` on puts even when the endpoint default is off; `0` disables it. Default is off for `.backblazeb2.com`/`*.backblazeb.com` (B2 rejects the header), on otherwise.
`AWC_S3_ACCESS_KEY_ID`	string	none	Access key id. Part of a credential pair.
`AWC_S3_SECRET_ACCESS_KEY`	string	none	Secret access key. Part of a credential pair.
`AWC_S3_SESSION_TOKEN`	string	none (absent)	Temporary session token. Read only when both the access key id and the secret are present.

Credentials load only when both AWC_S3_ACCESS_KEY_ID and AWC_S3_SECRET_ACCESS_KEY are set. Otherwise requests are made with no credentials.

Control plane (awc-control)¶

Read by the awc-control server.

Variable	Type	Default	Effect
`AWC_CONTROL_LISTEN`	`host:port`	`127.0.0.1:8080`	REST API listen address.
`AWC_CONTROL_GRPC_LISTEN`	`host:port`	`127.0.0.1:8081`	Internal gRPC listen address.
`AWC_CONTROL_TLS_CERT`	file path	none, required outside dev	Server TLS certificate file. Read for mutual-TLS gRPC.
`AWC_CONTROL_TLS_KEY`	file path	none, required outside dev	Server TLS private key file.
`AWC_CONTROL_TLS_CLIENT_CA`	file path	none, required outside dev	Client CA certificate file. Clients must present a certificate signed by this CA.
`AWC_SERVICE_TOKEN_KEY`	string	none, required outside dev	Secret key for signing service-account tokens. Required unless `AWC_DEV_MODE=1`.
`AWC_MOUNT_TICKET_SEED`	64-char hex	none, required outside dev	32-byte seed for signing mount tickets. Decoded from hex.
`AWC_MOUNT_TARGET_ROOTS`	comma-separated paths	`/opt/sandboxes`	Target-path roots stamped into every issued mount ticket.

Outside AWC_DEV_MODE=1, the three server TLS variables, AWC_SERVICE_TOKEN_KEY, and AWC_MOUNT_TICKET_SEED are all required. Startup fails if any is unset.

Control-plane client TLS (awcd)¶

Read by awcd when it connects to an https:// control plane.

Variable	Type	Default	Effect
`AWC_CONTROL_TLS_CA`	file path	none, required for `https://`	CA certificate file that signs the control plane server certificate.
`AWC_CONTROL_TLS_CERT`	file path	none, required for `https://`	Client certificate file for mutual TLS.
`AWC_CONTROL_TLS_KEY`	file path	none, required for `https://`	Client private key file for mutual TLS.

For an https:// endpoint, all three are required. For an http:// endpoint, the connection is refused unless AWC_DEV_MODE=1.

Worker (awc-worker)¶

Read by the awc-worker binary.

Variable	Type	Default	Effect
`AWC_WORKER_ID`	string	`awc-worker`	Per-process identifier. Each concurrent worker adds a `-<n>` suffix on its leases.
`AWC_WORKER_CONCURRENCY`	integer	`4`	Bounded worker count.
`AWC_WORKER_LEASE_SECS`	integer	`300`	Job visibility-lease length, in seconds.
`AWC_WORKER_POLL_INTERVAL_MS`	integer	`1000`	Idle poll interval, in milliseconds.
`AWC_RETENTION_GRACE_SECS`	integer	`86400`	How long an `EXPIRING` workspace stays reversible before it may be reaped.

Garbage collection (awc-worker)¶

Read by awc-worker.

Variable	Type	Default	Effect
`AWC_GC_GRACE_SECS`	integer	`86400`	Durable-GC safety grace. Objects newer than `now - grace` are never swept.
`AWC_GC_BATCH_SIZE`	integer	`1000`	Maximum candidate count deleted per epoch.
`AWC_GC_CANARY_SIZE`	integer	`10`	Size of the leading canary batch.
`AWC_GC_DRY_RUN`	`1`, `true`, or `TRUE`	unset (`false`)	Plan only, delete nothing. Any other value means `false`.

Host daemon (awcd)¶

Variable	Type	Default	Effect
`AWC_CGROUP_ROOTS`	colon-separated paths	empty	Cgroup roots scanned by the checkpoint runner.

CLI output and connection (awcctl)¶

Read by awcctl global flags. Each variable maps to a global --flag, which overrides the environment.

Variable	Type	Default	Effect
`AWC_OUTPUT`	enum: `text` or `json`	`text`	Output format. `json` is machine-readable.
`AWC_QUIET`	boolean	`false`	Suppress progress output on stderr. Results still print.
`AWC_HOST_SOCKET`	path	`/run/awcd/awcd.sock`	Path to the local `awcd` Unix socket.
`AWC_CONTROL_ENDPOINT`	URL	none	Base URL of the remote control plane. Required for control-plane commands.
`AWC_TOKEN`	string	none	Bearer token for control-plane authentication.
`AWC_TENANT`	string	none	Tenant id. Required for control-plane and snapshot-upload commands.
`AWC_PROJECT`	string	none	Project id. Required for most control-plane commands.
`AWC_IDEMPOTENCY_KEY`	string	none	Idempotency key for the next mutating request.

Socket defaults agree

AWC_HOST_SOCKET defaults to /run/awcd/awcd.sock in awcctl. The awcd binary uses the same default (set by positional argument or AWCD_SOCKET), and the systemd unit creates /run/awcd through RuntimeDirectory=awcd. When you run awcd without systemd, pass the socket path explicitly to both binaries.

Authentication and mount tickets¶

Variable	Type	Default	Read by	Effect
`AWC_SERVICE_TOKEN_KEY`	string	none, required outside dev	`awc-control`	Secret key for signing service-account tokens.
`AWC_MOUNT_TICKET_SEED`	64-char hex	none, required outside dev	`awc-control`	32-byte signing seed for issued mount tickets.
`AWC_MOUNT_TICKET_PUBLIC_KEY`	64-char hex	none, required outside dev	`awcd`	Public half of the mount-ticket signing key. Used to verify tickets.
`AWC_MOUNT_TICKET_PUBLIC_KEY_FILE`	file path	none	`awcd`	File that contains the 64-char hex public key. Used only when `AWC_MOUNT_TICKET_PUBLIC_KEY` is unset.

awcd reads AWC_MOUNT_TICKET_PUBLIC_KEY first, then falls back to AWC_MOUNT_TICKET_PUBLIC_KEY_FILE. Outside AWC_DEV_MODE=1, at least one must be set.

Dev mode¶

AWC_DEV_MODE is the master dev switch. When set to 1, several production guards relax. Read by awc-control (REST and gRPC setup) and awcd.

Variable	Type	Default	Effect
`AWC_DEV_MODE`	`1` to enable	unset (production)	When `1`: `awc-control` skips the mutual-TLS gRPC setup and does not require `AWC_SERVICE_TOKEN_KEY` or `AWC_MOUNT_TICKET_SEED`; `awcd` allows `http://` control-plane endpoints and falls back to a fixed dev ticket key.

The variables below are read only by awc-control, and only when AWC_DEV_BOOTSTRAP=1. They seed a local-dev identity. They have no effect otherwise.

Variable	Type	Default	Effect
`AWC_DEV_BOOTSTRAP`	`1` to enable	unset	When `1`: grant the dev principal the Admin role on the dev project and mint a full-scope service token.
`AWC_DEV_TENANT`	string	`ten_01arz3ndektsv4rrffq69g5fav`	Tenant id for the bootstrapped identity.
`AWC_DEV_PROJECT`	string	`prj_01arz3ndektsv4rrffq69g5fav`	Project id for the bootstrapped identity.
`AWC_DEV_PRINCIPAL`	string	`prin_01arz3ndektsv4rrffq69g5fav`	Principal id for the bootstrapped identity.

The dev token is minted only when AWC_SERVICE_TOKEN_KEY is also set. The bootstrap seeds a local-dev identity.

Test-only variables¶

These gate integration tests. They are not read by production code paths.

Variable	Type	Default	Read by	Effect
`AWC_PG_TESTS`	`1` to enable	unset	`awc-db`, `awc-control`, `awc-worker` tests	When `1`, Postgres integration tests run. If `DATABASE_URL` is empty, the test binary fails with a clear message.
`AWC_S3_TESTS`	`1` to enable	unset	`awc-cas` tests	When `1`, S3 integration tests run and require `AWC_S3_ENDPOINT` and `AWC_S3_BUCKET`.

Variable	Type	Default	Read by	Effect
`DATABASE_URL`	string	none, required	`awc-control`, `awc-worker`	PostgreSQL connection string. Startup fails if unset.
`AWCD_SOCKET`	path	`/run/awcd/awcd.sock`	`awcd`	Unix socket path for the `awcd` host API. Overridden by the second positional argument to `awcd`.

Current scope¶

The structured AWC_<SECTION>__<FIELD> layer is read only by awcd. awc-control and awc-worker do not load it; they read their own direct variables listed above.
There is no environment variable for the REST rate limiter. awc-control constructs an unlimited rate limiter in code. Throttling (spec §16.10) has no env knob in this build.
OIDC discovery is not wired. Only service-account tokens authenticate. The verifier starts from an empty static set, so a real identity provider is a follow-up.
The mount-ticket public-key verifier (awcd) uses a single configured key with a fixed validity window of 2020-01-01 through 2100-01-01. Key rotation is not exposed.
AWC_CGROUP_ROOTS is read only when the fuse feature is enabled.