Architecture

Axern separates durable product intent from node-local execution. Public clients address gatewayd, the unified external gateway for control and Allocation-scoped data-plane traffic. controld remains the authority for placement, lifecycle, leases, health, and resource state. Runtime services own the host operations needed to turn that intent into an isolated workload; internal lifecycle and status traffic does not route through gatewayd.

flowchart LR
    Clients["CLI · SDK consumers"] --> Gateway["gatewayd\npublic control + data edge"]
    Gateway -->|control APIs + target resolution| Control["controld\ndurable intent + placement"]
    Control --> Postgres[(PostgreSQL)]
    Control -->|lifecycle| Node["axnoded\nsandbox lifecycle"]
    Node -->|status + capabilities| Control
    Gateway -->|Allocation operations| Node
    Gateway -->|client peer| Tunnel["tunneld\nreverse TCP relay"]
    Node -->|node peer| Tunnel
    Node --> Image["imagemgr + imagefsd\nOCI + Nydus"]
    Node --> Runtime["runsc"]

Stable ownership

• Gateway: authenticates public clients and forwards control, process, file, archive, terminal, SSH, and Tunnel traffic without owning durable state.
• Control plane: persists resources and coordinates placement, leases, health, allocation-scoped status, and cleanup.
• Node runtime: owns sandbox processes, filesystems, images, networking (an eBPF NAT dataplane with an explicit iptables rollback; see Node Networking), probes, and node-local reconciliation.
• SDKs: expose Sandbox ergonomics over the durable Environment -> Run -> Allocation chain without creating another workload model.

This page intentionally stays conceptual. The repository’s runtime architecture, resource model, and execution lifecycle are the engineering sources of truth.