Box — OCI Container Runtime

• *rea:*infra/net/
• *ath:*infra/net/box
• *lug:*koder-box (alias kbox)
• *ind:*OCI-compatible container runtime + image manager (Go)
• *ersion:*v1.1.0 (CHANGELOG: infra/net/box/CHANGELOG.kmd)
• *elfhosted pair:*row 13 of [`registries/selfhostedpairs.md`](..registriesselfhostedpairs.md) — replaces DockerPodmancontainerdbuildahnerdctl. Status: *table*for singlenode runtimebuildregistrycomposeCRIU; experimental for clusterCDIWASMCVEICP-Brasil signing.

Role in the stack

Box is the Koder OCI container runtime — the layer that actually runs containerized applications on top of infra/linux/distro. Every Koder service or product packaged as an OCI image (whether deployed via infra/net/cloud or a manual server provision) ultimately runs inside Box.

It is the substrate for multitenant compute: namespace isolation, cgroup resource limits, lifecycle management, image pulling, layer storage, volume mounts. v1.1.0 added live checkpointrestore (CRIU), distributed build farm, and modern rootless networking (pasta, macvlanipvlan, netavark/aardvarkdns).

Surfaces

Configuration

/etc/koder-box/default.toml (TOML) → KODER_BOX_* env overrides → CLI flags. The TOML loader landed in #104 (Go 1.24+, BurntSushi/toml); the schema mirrors the JSON-tagged internal/config.Config. Missing file is silent (defaults kept); malformed file is a startup error.

Multi-tenancy

Every container carries a KoderUserID field and an OCI label dev.koder.tenant.user_id (mirrors). The REST API resolves the tenant from the X-Koder-User-ID request header (until OAuth Koder ID daemon auth lands — ticket #110); listinspect handlers filter by tenant, and cross-tenant lookups return 404 (not 403) per `specsmulti-tenancy/contract.kmd. Legacy containers without the field resolve to the special tenant unknown` so they remain visible to administrators during the migration window. Landed in #108.

Primary couplings