Specifications

Badges

Spec Index

Note on row-level status. The header Status column below is canonical per-spec. Inside each spec's index.md, the per-requirement table (rows like S006-FR-001 | … | Draft) has not been refreshed since initial drafting — most rows still read Draft even where the feature is in production. S000, S001, and S013 are up to date; the rest will be reconciled in a sweep that walks the code and updates row statuses individually. For now, trust the spec-header Status and the ## Implementation note blocks at the bottom of each spec.

Startup Sequence

outcalld initializes subsystems in dependency order. Each subsystem waits for its prerequisites before starting. Failure at any P1 step aborts startup.

1. Bridge (S001)          — create/attach bridge, apply nftables base rules
   ↓
2. Rule Engine (S003)     — load YAML rule files, validate CEL expressions
   ↓
3. Network (S002)         — create default Docker network, assign bridge gateway IP
   ↓ (parallel)
4a. DNS Filter (S007)     — bind DNS server to bridge gateway IP (from S002)
4b. HTTP Proxy (S006)     — bind proxy to bridge gateway IP (from S002)
   ↓
5. Docker Manager (S008)  — initialize Docker client, ready to create containers
   ↓
6. Host API               — bind unix socket, start serving
   ↓
7. Agent API (S004)       — bind agent socket, ready for agent check-ins

Shutdown sequence (reverse order)

7. Agent API              — stop accepting new requests, drain in-flight
6. Host API               — stop accepting new requests
5. Docker Manager         — (containers are NOT stopped — they outlive the daemon)
4. DNS/Proxy              — stop listeners
3. Network                — (networks are NOT removed — they outlive the daemon)
2. Rule Engine            — (no cleanup needed)
1. Bridge (S001)          — flush nftables table, delete bridge interface

Note: networks and containers intentionally outlive the daemon (S002-EC-010). The bridge and nftables rules are torn down so that traffic is no longer filtered — containers lose connectivity until the daemon restarts.

Design Principles

1. Default BLOCK — no rule match means denied. Every subsystem enforces this independently.
2. Fail closed — if any subsystem is unavailable, the answer is BLOCK/deny/SERVFAIL/exit-5.
3. Host-only management — bridge, network, rule, and container management happens on host.sock only.
4. Agent isolation — containers see only agent.sock. No access to host API, bridge, or nftables.
5. Single binary — everything runs as Tokio tasks in outcalld. No separate processes.