Configuration

Reference for every component’s configuration surface. Two rules hold across the codebase:

  • Gateway and sandlot accept CLI flags plus an optional -config <yaml> (an explicitly-set flag overrides the YAML value; unset flags fall through to the file, then to built-in defaults). Production command lines/config files are generated by the deployers (bare-metal scripts or the K8s units) — but a hand-written YAML is fully supported. sandns is YAML-only; the warden is kernel-cmdline
    • environment only (written by the sandlot at VM create).
  • Everything hot-reloadable is marked so; the rest requires a component restart (see §4).

1. Components

Component Surface Page
gateway CLI flags + optional YAML (-config) Gateway
sandlot CLI flags + optional YAML (-config) Sandlot
boxout CLI flags + shared sandlot YAML (microvm.* subset hot-reloads) Boxout
sandns YAML config file (hot-reloadable sections) Sandns
warden kernel cmdline + environment variables Warden

Each component page opens with a mode/role applicability matrix and marks every section with its Scope — which gateway mode or sandlot role the knobs apply to — so an operator configures one instance without reading the whole page.

2. Cross-component invariants

The deployment rules that span components. Breaking any of these is a silent-failure class — the pieces each validate their own side, so a mismatch surfaces as behavior, not an error message.

2.1 Sizing the stream (gateway ↔ sandlot)

Rule Why
gateway -stream-send-buffer ≥ sandlot -max-concurrent-commands (both default 2000) the send channel must absorb the node’s full command concurrency or requests stall at dispatch
gRPC stream-max-msg-size-mb ≥ 16 on both sides a FileOp under the warden caps must survive the gRPC frame limit
HTTP/2 windows (initial-window 64 MB / initial_conn_window 128 MB) sized for concurrency headroom 64 MB holds ~4 concurrent 16 MB FileOps

2.2 The 16 MB chain (/agent/file)

Warden max_file_read_bytes / max_body_len ≥ 16 MB and both gRPC max_msg_size ≥ 16 MB, so an op accepted over HTTP is never rejected at the vsock layer. The HTTP body limit stays 50 MB (never 16): a 16 MB binary write inflates to ~21 MB through base64+JSON.

2.3 Timeout chain (sync exec)

Gateway -default-exec-timeout-sec (30) < gateway -max-exec-timeout-sec (180) ≤ warden max_exec_timeout < warden warden_countdown_sec (300). Each hop re-checks; leave real headroom before the countdown (the sandlot warns when the gap ≤ 30 s). Background execs are exempt — bounded by their absolute lease_duration.

2.4 Resilience clocks

T_tolerance (sandlot -tolerance-sec) > T_clean (-cleanup-sec) and > T_warden (-warden-countdown-sec); gateway derives T_safe = T_tolerance + T_warden + 60s as the presence TTL. The gateway validates the inequality per node at connect — a node with impossible timings is rejected, not degraded.

2.5 Staleness threshold copies

sandns’s staleness.route_stale_sec and the gateway’s -route-stale-sec are separately configured copies of one semantic — keep them equal (20 s default). Drift shows up as sandns and the 307 gate disagreeing about whether an owner is dead.

3. Precedence rules

Component Order
gateway / sandlot explicit CLI flag > YAML -config value > default
warden environment variable > kernel cmdline warden.* > TOML config file (if set; base values only) > default
sandns YAML only; unknown keys fail at startup
boxout flag > shared sandlot YAML section > default

4. Hot-reload by component

Component Hot-reloads Restart-required
gateway lease.*, exec.* (incl. background-lease cap), sched.*, shed.*, selfload.*, staleness.* (incl. etcd_fence_sec), ownership.cache_ttl_sec, unmount_stats.*, MCP instructions-file content (path is restart) listeners/TLS, etcd, stream transport, identity loading/store, authn, top level (vol_root/mode/gateway_id/…)
sandlot microvm.kernel/initramfs/default_vcpus/default_memory_mb (new VMs only), pool (resize both directions), recycle.*, provision.volume_seed* (rotation stage/abort/promote) gateway_addr/node_id/vm_mode, microvm.volumes_dir/overlayfs_templates/warden_*, specs, instance.*, stream.*, resilience.*, network.*, tls.*, provision.* (incl. the OCI registry + its credentials)
sandns scheduling.*, staleness.* (file watcher; k8s ConfigMap atomic updates work) listen_addr, domains.*, etcd*, ttl, sticky_*, forwarders, owners.* + the other sizing knobs (sticky_max, max_concurrent_queries, forward_concurrency, tcp_max_conns)
warden nothing — boot-time only (a change lands on the next VM via pool recycling) everything
boxout the microvm.* subset sandlot also classifies hot (kernel/initramfs/default resources — tracked from the shared sandlot YAML so create_vm’s parameter whitelist stays in sync) everything else (network, socket, allowed-uid)

Details and per-knob semantics: the component pages above.


Table of contents