Configuration reference¶

This page lists every awcd configuration knob. It covers the file keys, the matching environment variables, the defaults, and the validation rules. The normative source is spec §22.9.

Sources and precedence¶

awcd resolves its configuration from layered sources. Later sources override earlier ones, field by field. A field that is left unset falls back to the next source, and then to its default.

file  <  environment  <  flags

Source	How it is supplied	Notes
File	First positional argument to `awcd`.	Parsed as TOML. See awcd daemon reference.
Environment	Variables with the `AWC_` prefix.	Nested keys use a `__` separator.
Flags	A pre-built layer passed to the `awc-config` library.	The `awcd` binary does not apply a flags layer. It uses the file and environment sources only.

Merge rules:

A set value in a later layer replaces the value from an earlier layer.
Nested tables merge field by field. A file [cache] max_bytes and an environment AWC_CACHE__MAX_REMOTE_FETCHES both survive.
Numeric limits fall back to their spec defaults when no layer sets them.
Mandatory deployment fields have no default. At least one layer must set them.

File format¶

The daemon parses the file as TOML. The config library also supports JSON, but awcd uses TOML only. Spec §22.9 shows the keys in a YAML block. The keys match; the surface syntax differs. Use TOML on disk.

Daemon invocation¶

awcd <config.toml|-> [socket-path]

<config.toml>: path to a TOML file. Use - to skip the file and configure from the environment only.
[socket-path]: host API Unix socket. Falls back to AWCD_SOCKET, then to /run/awcd/awcd.sock.

The daemon exits with FAILURE when the config path is missing, when a required field is unset, or when validation fails. See awcd daemon reference for the full lifecycle.

Configuration keys¶

Every key below can be set in the file or in the environment. The Env var column gives the exact environment name. Top-level keys use a flat name. Keys under [cache], [checkpoint], and [leases] use an AWC_<SECTION>__<KEY> name.

Top-level keys¶

Key	Type	Default	Env var	Validation and effect
`host_id`	string (`host_<ulid>`)	required	`AWC_HOST_ID`	Identifier of the local host. Must parse as `host_` followed by a ULID (spec §9.1).
`control_plane_endpoint`	URL	required	`AWC_CONTROL_PLANE_ENDPOINT`	Control plane endpoint. Must use the `http` or `https` scheme. Used for lease lookup and checkpoint publish.
`basefs_mount`	absolute path	required	`AWC_BASEFS_MOUNT`	Mount point for the read-only base filesystem. Must be absolute and distinct from the other roots.
`cache_root`	absolute path	required	`AWC_CACHE_ROOT`	Root directory of the local content cache. Must be absolute and distinct from the other roots.
`workspace_root`	absolute path	required	`AWC_WORKSPACE_ROOT`	Root directory for per-workspace merged mounts. Must be absolute and distinct from the other roots.
`allowed_bind_roots`	array of absolute paths	`[]` (empty)	`AWC_ALLOWED_BIND_ROOTS`	Host paths that may be used as bind targets. Environment value is a comma-separated list. Every entry must be absolute.
`health_http_listen`	string (`host:port`)	unset (disabled)	`AWC_HEALTH_HTTP_LISTEN`	Loopback address for the liveness, readiness, and metrics HTTP endpoints (spec §19.6). When unset, the HTTP server is disabled and the host API stays on the Unix socket. Should be a loopback address.

`[cache]`¶

Key	Type	Default	Env var	Validation and effect
`max_bytes`	`u64`	`1000000000000`	`AWC_CACHE__MAX_BYTES`	Total byte limit of the local cache. Must be greater than zero.
`min_free_bytes`	`u64`	`50000000000`	`AWC_CACHE__MIN_FREE_BYTES`	Free space to preserve on the host filesystem. Drives the disk-pressure governor ladder (spec §17.8).
`max_remote_fetches`	`u32`	`128`	`AWC_CACHE__MAX_REMOTE_FETCHES`	Bound on object-store read concurrency.
`max_remote_fetches_per_tenant`	`u32`	`32`	`AWC_CACHE__MAX_REMOTE_FETCHES_PER_TENANT`	Per-tenant bound on object-store read concurrency. Must not exceed `max_remote_fetches`.
`max_prefetch_fetches`	`u32`	`8`	`AWC_CACHE__MAX_PREFETCH_FETCHES`	Prefetch concurrency. Must not exceed `max_remote_fetches`.

`[checkpoint]`¶

Key	Type	Default	Env var	Validation and effect
`max_concurrent`	`u32`	`4`	`AWC_CHECKPOINT__MAX_CONCURRENT`	Maximum concurrent checkpoint uploads. Must be greater than zero.
`freeze_timeout_seconds`	`u64`	`10`	`AWC_CHECKPOINT__FREEZE_TIMEOUT_SECONDS`	Freeze or quiesce timeout for cutting a checkpoint. Must be greater than zero.
`preserve_local_grace_seconds`	`u64`	`3600`	`AWC_CHECKPOINT__PRESERVE_LOCAL_GRACE_SECONDS`	Grace period for preserving local changes after a checkpoint. Must be greater than zero.

`[leases]`¶

Key	Type	Default	Env var	Validation and effect
`renew_interval_seconds`	`u64`	`30`	`AWC_LEASES__RENEW_INTERVAL_SECONDS`	How often the holder renews the lease. Must be strictly less than `expiry_seconds`.
`expiry_seconds`	`u64`	`90`	`AWC_LEASES__EXPIRY_SECONDS`	Lease lifetime before automatic expiry.
`disconnected_grace_seconds`	`u64`	`60`	`AWC_LEASES__DISCONNECTED_GRACE_SECONDS`	Grace period for a disconnected holder before revocation. Must be greater than zero.

Object-store endpoint¶

The object-store endpoint is environment only. It is not part of awcd.toml. The daemon reads AWC_CAS_URL to select the transport, then reads the transport-specific variables.

Env var	Required	Default	Validation and effect
`AWC_CAS_URL`	no	`memory://`	Selects the verified-cache transport. Accepted values are `memory://` for the in-memory store and `s3://` for the S3-compatible transport. The `s3://` value requires that `awcd` was built with the `s3` feature. Any other value fails startup.
`AWC_S3_ENDPOINT`	yes, when `AWC_CAS_URL=s3://`	none	Service endpoint, as scheme plus host and optional port. Must be an absolute URL.
`AWC_S3_BUCKET`	yes, when `AWC_CAS_URL=s3://`	none	Bucket name. May not be empty.
`AWC_S3_REGION`	no	`us-east-1`	SigV4 signing region.
`AWC_S3_KEY_PREFIX`	no	empty	Key prefix applied before the canonical CAS key. A single bucket can host several deployments under disjoint prefixes.
`AWC_S3_ACCESS_KEY_ID`	no	none	Access key id. Credentials activate only when this and `AWC_S3_SECRET_ACCESS_KEY` are both set.
`AWC_S3_SECRET_ACCESS_KEY`	no	none	Secret access key. Credentials activate only when this and `AWC_S3_ACCESS_KEY_ID` are both set.
`AWC_S3_SESSION_TOKEN`	no	none	Optional session token. Ignored when empty.

The object-store request path is scoped to a tenant prefix (spec §9.2). Agents do not receive object-store credentials (spec §13.2).

Validation invariants¶

Startup rejects contradictory or unsafe settings (spec §22.9). The resolver checks the following before the daemon starts:

basefs_mount, cache_root, and workspace_root are three distinct paths.
cache.max_remote_fetches_per_tenant is less than or equal to cache.max_remote_fetches.
cache.max_prefetch_fetches is less than or equal to cache.max_remote_fetches.
cache.max_bytes is greater than zero.
checkpoint.max_concurrent is greater than zero.
checkpoint.freeze_timeout_seconds is greater than zero.
checkpoint.preserve_local_grace_seconds is greater than zero.
leases.renew_interval_seconds is strictly less than leases.expiry_seconds.
leases.disconnected_grace_seconds is greater than zero.
control_plane_endpoint uses the http or https scheme.
Every entry in allowed_bind_roots is an absolute path.
host_id parses as host_<ulid>.
health_http_listen parses as a host:port socket address when set.

Worked example¶

host_id = "host_01arz3ndektsv4rrffq69g5fav"
control_plane_endpoint = "https://control.example"
basefs_mount = "/var/lib/awc/basefs"
cache_root = "/var/lib/awc/cache"
workspace_root = "/var/lib/awc/workspaces"
allowed_bind_roots = ["/var/lib/agent-sandboxes"]
health_http_listen = "127.0.0.1:9100"

[cache]
max_bytes = 1000000000000
min_free_bytes = 50000000000

[checkpoint]
max_concurrent = 4

[leases]
renew_interval_seconds = 30
expiry_seconds = 90
disconnected_grace_seconds = 60

With the file above, an operator can narrow the cache limit from the environment without editing the file:

export AWC_CACHE__MAX_BYTES=200000000000
awcd /etc/awc/awcd.toml

Current scope¶

The flags layer is a capability of the config library. The awcd binary does not feed command-line flags into the config layer. Its only positional arguments are the config path and the socket path.
The library can parse a JSON config file. The daemon hardcodes TOML and ignores JSON on disk.
The object-store endpoint, the mount-ticket verifier key, and the checkpoint cgroup roots are environment only. The socket path is a positional argument with an AWCD_SOCKET fallback. None of them has a key in awcd.toml. These runtime variables are covered on the environment variables page.
Every knob listed in spec §22.9 is implemented and validated in the current build.