Reference

Configuration reference

Configure the daemon, runtime, runner, manager, gateway, console, and observability policy.

On this page+

Baseline document
Section ownership
Merge rules
Precedence and environment
Defaults and validation

Baseline document

config/prd.yml is the checked baseline for daemon behavior and host-side manager policy. The Docker gateway reads its manager and optional gateway sections, then uploads the same document so sandbox-daemon serve --config-yaml can read the runtime sections inside each container.

config/prd.yml (abridged)

daemon:
  server:
    socket_path: /eos/runtime/daemon/runtime.sock
    pid_path: /eos/runtime/daemon/runtime.pid
    max_worker_threads: 32

runtime:
  workspace:
    layer_stack_root: /eos/layer-stack
    scratch_root: /eos/workspace
    setup_timeout_s: 30
    exit_grace_s: 0.25
    rfc1918_egress: allow
  namespace_execution:
    scratch_root: /eos/namespace_execution
  layerstack:
    autosquash_policies:
      squash_at_n_layers: 100

runner:
  mount_mask:
    hidden_paths: [/eos]

manager:
  docker:
    privileged: false
    daemon_binary_path: dist/sandbox-daemon-linux-arm64
    daemon_config_yaml_path: config/prd.yml

Host paths in manager resolve from the gateway working directory. The checked file also injects Docker Desktop proxy variables because the Engine API does not copy the Docker CLI proxy configuration into new containers.

Section ownership

Section	Owner	What it controls
`daemon`	Sandbox daemon	Unix socket, PID file, and worker count.
`runtime`	Runtime services	Workspace paths, setup and exit timing, egress, namespace scratch, and autosquash.
`runner`	Namespace runner	Mount masking, including paths hidden from commands.
`observability`	Telemetry	Optional retention and sampling policy; missing means typed defaults.
`manager`	Host manager/provider	Workspace picker roots, Docker boundary, artifacts, uploaded config, and container environment.
`gateway`	Gateway server	Bind address, PID path, and connection limit; authentication never comes from YAML.
`console`	Console server	Bind address and RPC, health, proxy, resolution, and cache timeouts.

manager.workspace_roots is optional. When present, it must be a non-empty list of absolute directories and create_sandboxmust select one of them. When absent, the console picker begins at the gateway user's home directory without narrowing existing API paths.

Merge rules

Tests may load one local YAML override after prd.yml. Objects merge recursively, scalars replace baseline values, arrays replace whole arrays, and omitted keys inherit. Unknown keys and wrong types are errors; null is valid only for a typed optional field.

Test merge order

config/prd.yml
  -> crates/<crate>/tests/**/<name>.test.yml

Operation names, protocol fields, schema versions, file-layout names, and kernel constants are static contracts. They belong in Rust, not in YAML overrides.

Precedence and environment

Gateway and console command-line flags override environment variables, which override their YAML sections, which override typed defaults. The repository launchers add one discovery layer for file paths and token loading.

Variable	Purpose
`SANDBOX_GATEWAY_CONFIG_YAML`	Baseline path used by the Docker gateway launcher.
`SANDBOX_GATEWAY_SOCKET`	Gateway endpoint used by launchers and clients unless an explicit flag wins.
`SANDBOX_GATEWAY_TOKEN_FILE`	Private token-file location used by repository wrappers.
`SANDBOX_GATEWAY_AUTH_TOKEN`	Runtime credential; never a YAML field.
`SANDBOX_CONSOLE_CONFIG_YAML`	Console YAML path when `--config-yaml` is absent.
`SANDBOX_CONSOLE_BIND`	Console listener when `--bind` is absent.
`SANDBOX_CONSOLE_ASSETS`	Built SPA directory when `--assets-dir` is absent.
`EOS_GATEWAY_BACKEND`	Gateway provider when `--backend` is absent.

The Docker launcher always selects the Docker backend and passes its chosen config path. See Installation for the supported startup workflow.

Defaults and validation

Missing optional sections load typed Rust defaults. The gateway listens on 127.0.0.1:7878, writes /tmp/eos-gateway.pid, and allows 256 concurrent connections. The console listens on 127.0.0.1:7880. Both defaults are loopback-only.

Loading validates socket addresses, absolute paths, non-empty values, numeric lower bounds, and section-specific invariants before services start. Treat a configuration error as a schema failure: correct the named field instead of adding an unrecognized compatibility key.