# footprintai/containarium architecture

> Architecture diagram of the GitHub repository footprintai/containarium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/footprintai/containarium
- Repository: https://github.com/footprintai/containarium

## Overview

1. **Repository shape**
   - This is a Go-first monorepo with a small TypeScript agent runtime and a Next.js web UI. The core platform is in `internal/`, substrate adapters are in `pkg/core/`, public API contracts are in `proto/` and generated `pkg/pb/`, and all runnable entrypoints live under `cmd/`.

2. **Primary control-plane entrypoints**
   - `cmd/containarium` is the main operator CLI.
   - `cmd/mcp-server` is the platform MCP server for host-level operations.
   - `cmd/agent-box` is the in-container MCP server exposed to the agent itself.
   - `cmd/containarium`, `cmd/mcp-server`, and the daemon-facing packages share the same underlying service logic rather than duplicating workflows.

3. **Top-level runtime topology**
   - The architecture has a public **sentinel** edge and one or more **backend hosts** behind it.
   - The sentinel handles inbound SSH and HTTPS routing; backend hosts run the daemon and the tenant boxes.
   - The same control plane can target either **Incus/LXC** or **Kubernetes** backends at runtime.

4. **Agent execution boundary**
   - Each tenant gets a persistent “box” that is SSH-reachable and also exposes MCP tools from inside the box.
   - The data path is: agent client → SSH to box → `agent-box` MCP over stdio.
   - `internal/agentbox` implements the in-box file, shell, and directory tools, plus a constrained root via `AGENTBOX_ROOT` when enabled.

5. **Host-side orchestration and reconciliation**
   - `internal/server` contains the daemon’s business logic: container lifecycle, networking, routes, secrets, security, alerts, traffic, autosleep, and higher-level orchestration.
   - `pkg/core/box/incus` and `pkg/core/box/k8s` are the substrate adapters for the two runtimes.
   - `internal/app` and related packages model apps, routes, buildpacks, proxies, and route synchronization across the backend.

6. **Public ingress and routing**
   - The sentinel uses SSH proxying for user login into boxes and Caddy for hostname-based HTTPS exposure.
   - `internal/sentinel`, `internal/wake`, `internal/egressproxy`, and `internal/network`/`internal/traffic` coordinate SSH routing, wake/recovery, passthrough, egress control, and traffic accounting.
   - Public app exposure is split between low-level route management and higher-level `expose-port` workflows.

7. **Security and tenancy boundaries**
   - Authentication is JWT-based for the API, with scopes, revocation, and role checks enforced in `internal/auth` and `internal/server`.
   - Tenant ownership and admin-only boundaries are explicit in the server handlers.
   - Secrets are stored encrypted through `pkg/core/secrets` and `internal/secrets`, backed by Postgres plus optional external KMS.
   - Audit data is append-only with a hash chain in `internal/audit`.

8. **Networking and policy enforcement**
   - The repo treats network policy as a first-class subsystem, not just a deployment concern.
   - `internal/netpolicy`, `internal/netbpf`, and `internal/server/network_policy_*` implement egress policy, signature-based rules, and kernel-level enforcement hooks.
   - The design spans both backend substrates so the policy model stays consistent across LXC and Kubernetes.

9. **API contract and transport layers**
   - `proto/containarium/**` defines the canonical API surface.
   - Generated gRPC services plus gRPC-Gateway handlers live in `pkg/pb/**`, giving the daemon both gRPC and REST entrypoints.
   - Swagger is checked in under `api/swagger/`, which supports the UI and external clients.

10. **Web UI and human-facing management**
   - `web-ui/` is a separate Next.js frontend that talks to the platform APIs and event stream.
   - It focuses on container lists, lifecycle controls, metrics, audit, security, network, traffic, and browser-based terminal access.
   - The UI is a consumer of the control plane, not a parallel source of truth.

11. **Agent/model-side tooling**
   - `agent-runtime/` is a TypeScript package for driving model backends such as Claude, Codex, and Gemini.
   - It contains polling, artifact handling, and A2A/engine abstractions, so agent orchestration can sit outside the Go daemon.
   - This is adjacent to the platform rather than part of the host runtime itself.

12. **Operational and deployment boundary**
   - `terraform/` and `deploy/` define production infrastructure, especially GCE and Kubernetes packaging.
   - `scripts/`, `hacks/`, and `images/` hold bootstrap, install, and container image assembly logic.
   - The repo is designed to be deployed either as a self-hosted VM stack or inside an existing Kubernetes environment, with the same control surface in both cases.

Main entry points: [`internal/server`](https://github.com/footprintai/containarium/tree/main/internal/server) (Daemon), [`internal/sentinel`](https://github.com/footprintai/containarium/tree/main/internal/sentinel) (Sentinel), [`internal/agentbox`](https://github.com/footprintai/containarium/tree/main/internal/agentbox) (Agent Box), [`proto/containarium`](https://github.com/footprintai/containarium/tree/main/proto/containarium) (API Surface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtimes["Runtimes"]
  node_agentrt["Agent Runtime<br/>ts package"]
  node_webui["Web UI<br/>next.js frontend"]
end

subgraph group_grp_control["Control plane"]
  node_sentinel(("Sentinel<br/>edge router"))
  node_daemon["Daemon<br/>host service"]
  node_appsys["Apps<br/>app orchestration"]
  node_agentbox["Agent Box<br/>in-box MCP"]
  node_mcp["MCP API<br/>tool gateway"]
  node_auth["Auth<br/>jwt/rbac"]
  node_secrets[("Secrets<br/>encrypted store")]
  node_audit["Audit<br/>append log"]
  node_netpol["Net Policy<br/>policy engine"]
  node_traffic[("Traffic<br/>accounting")]
  node_wake["Wake<br/>routing/recovery"]
  node_api["API Surface<br/>proto/grpc-rest"]
  node_cli["CLI<br/>go entrypoints"]
end

subgraph group_grp_substrate["Substrates"]
  node_core["Core Adapters<br/>substrate layer"]
  node_incus["Incus<br/>container backend"]
  node_k8s["K8s<br/>cluster backend"]
  node_hosting["Hosting<br/>caddy/dns"]
  node_pb["Generated PB<br/>generated api"]
end

subgraph group_grp_ops["Ops"]
  node_deploy["Deploy<br/>infra"]
end

node_sentinel -->|"SSH routing"| node_wake
node_sentinel -->|"HTTPS exposure"| node_hosting
node_sentinel -.->|"backend host"| node_daemon
node_daemon -->|"uses adapters"| node_core
node_daemon -->|"runtime backend"| node_incus
node_daemon -->|"runtime backend"| node_k8s
node_daemon -->|"app control"| node_appsys
node_daemon -->|"secret ops"| node_secrets
node_daemon -->|"audit trail"| node_audit
node_daemon -->|"enforces policy"| node_netpol
node_daemon -->|"measures flows"| node_traffic
node_daemon -->|"serves API"| node_api
node_api -->|"generated handlers"| node_pb
node_cli -->|"operator control"| node_daemon
node_cli -->|"mcp tools"| node_mcp
node_agentbox -->|"stdio tools"| node_mcp
node_agentbox -->|"root boundary"| node_auth
node_agentrt -->|"drives agents"| node_mcp
node_webui -->|"consumes api"| node_api
node_daemon -->|"tenant boxes"| node_agentbox

click node_sentinel "https://github.com/footprintai/containarium/tree/main/internal/sentinel"
click node_daemon "https://github.com/footprintai/containarium/tree/main/internal/server"
click node_appsys "https://github.com/footprintai/containarium/tree/main/internal/app"
click node_agentbox "https://github.com/footprintai/containarium/tree/main/internal/agentbox"
click node_mcp "https://github.com/footprintai/containarium/tree/main/internal/mcp"
click node_auth "https://github.com/footprintai/containarium/tree/main/internal/auth"
click node_secrets "https://github.com/footprintai/containarium/tree/main/internal/secrets"
click node_audit "https://github.com/footprintai/containarium/tree/main/internal/audit"
click node_netpol "https://github.com/footprintai/containarium/tree/main/internal/netpolicy"
click node_traffic "https://github.com/footprintai/containarium/tree/main/internal/traffic"
click node_wake "https://github.com/footprintai/containarium/tree/main/internal/wake"
click node_api "https://github.com/footprintai/containarium/tree/main/proto/containarium"
click node_core "https://github.com/footprintai/containarium/tree/main/pkg/core"
click node_incus "https://github.com/footprintai/containarium/tree/main/pkg/core/incus"
click node_k8s "https://github.com/footprintai/containarium/tree/main/pkg/core/box/k8s"
click node_hosting "https://github.com/footprintai/containarium/tree/main/internal/hosting"
click node_pb "https://github.com/footprintai/containarium/tree/main/pkg/pb/containarium"
click node_agentrt "https://github.com/footprintai/containarium/tree/main/agent-runtime"
click node_webui "https://github.com/footprintai/containarium/tree/main/web-ui"
click node_cli "https://github.com/footprintai/containarium/tree/main/cmd"
click node_deploy "https://github.com/footprintai/containarium/tree/main/terraform"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agentrt,node_webui toneBlue
class node_sentinel,node_daemon,node_appsys,node_agentbox,node_mcp,node_auth,node_secrets,node_audit,node_netpol,node_traffic,node_wake,node_api,node_cli toneAmber
class node_core,node_incus,node_k8s,node_hosting,node_pb toneMint
class node_deploy toneRose
```

## Components

### Runtimes

User-facing and agent-side runtimes outside the Go control plane.

- [Agent Runtime](https://github.com/footprintai/containarium/tree/main/agent-runtime): ts package · TypeScript agent/model runtime for polling, artifacts, and model engines. · `agent-runtime`
- [Web UI](https://github.com/footprintai/containarium/tree/main/web-ui): next.js frontend · Human-facing management UI for control-plane data and events. · `web-ui`

### Control plane

Go services, daemon logic, and API handlers.

- [Sentinel](https://github.com/footprintai/containarium/tree/main/internal/sentinel): edge router · Public ingress edge for SSH, HTTPS, and host routing. · `internal/sentinel`
- [Daemon](https://github.com/footprintai/containarium/tree/main/internal/server): host service · Main host-side control service and orchestration entrypoint. · `internal/server`
- [Apps](https://github.com/footprintai/containarium/tree/main/internal/app): app orchestration · App lifecycle, routes, proxies, buildpacks, and route sync. · `internal/app`
- [Agent Box](https://github.com/footprintai/containarium/tree/main/internal/agentbox): in-box MCP · MCP tool server running inside each tenant box. · `internal/agentbox`
- [MCP API](https://github.com/footprintai/containarium/tree/main/internal/mcp): tool gateway · Shared MCP client/server plumbing and tool wiring. · `internal/mcp`
- [Auth](https://github.com/footprintai/containarium/tree/main/internal/auth): jwt/rbac · JWT auth, scopes, revocation, roles, and tenant boundaries. · `internal/auth`
- [Secrets](https://github.com/footprintai/containarium/tree/main/internal/secrets): encrypted store · Secret encryption, KMS integration, and secret reconciliation. · `internal/secrets`
- [Audit](https://github.com/footprintai/containarium/tree/main/internal/audit): append log · Append-only audit trail with hash chaining. · `internal/audit`
- [Net Policy](https://github.com/footprintai/containarium/tree/main/internal/netpolicy): policy engine · Network policy model, signatures, and enforcement coordination. · `internal/netpolicy`
- [Traffic](https://github.com/footprintai/containarium/tree/main/internal/traffic): accounting · Connection tracking, flow collection, and traffic storage. · `internal/traffic`
- [Wake](https://github.com/footprintai/containarium/tree/main/internal/wake): routing/recovery · SSH wake, recovery, trusted proxy handling, and routing state. · `internal/wake`
- [API Surface](https://github.com/footprintai/containarium/tree/main/proto/containarium): proto/grpc-rest · Canonical protobuf contracts plus generated gRPC and REST handlers. · `proto/containarium`
- [CLI](https://github.com/footprintai/containarium/tree/main/cmd): go entrypoints · Operator entrypoints for the main CLI, MCP server, and agent box server. · `cmd`

### Substrates

Runtime adapters and lower-level platform integrations.

- [Core Adapters](https://github.com/footprintai/containarium/tree/main/pkg/core): substrate layer · Shared substrate abstractions for boxes, secrets, networking, and core services. · `pkg/core`
- [Incus](https://github.com/footprintai/containarium/tree/main/pkg/core/incus): container backend · Incus/LXC box backend adapter. · `pkg/core/incus`
- [K8s](https://github.com/footprintai/containarium/tree/main/pkg/core/box/k8s): cluster backend · Kubernetes box backend adapter and gateway support. · `pkg/core/box/k8s`
- [Hosting](https://github.com/footprintai/containarium/tree/main/internal/hosting): caddy/dns · Hostname exposure, Caddy integration, and provider setup. · `internal/hosting`
- [Generated PB](https://github.com/footprintai/containarium/tree/main/pkg/pb/containarium): generated api · Generated protobuf services and gRPC-Gateway shims. · `pkg/pb/containarium`

### Ops

Deployment and release machinery.

- [Deploy](https://github.com/footprintai/containarium/tree/main/terraform): infra · Terraform, scripts, images, and deploy manifests for production and lab setups. · `terraform`

## Connections

- Sentinel → Wake: SSH routing · Sentinel forwards login and recovery flows through wake/router logic.
- Sentinel → Hosting: HTTPS exposure · Sentinel uses hostname-based HTTPS and Caddy-backed exposure.
- Sentinel → Daemon: backend host · Sentinel fronts backend hosts where the daemon and tenant boxes run.
- Daemon → Core Adapters: uses adapters · Daemon business logic is built on shared core substrate abstractions.
- Daemon → Incus: runtime backend · Daemon can manage boxes on Incus/LXC.
- Daemon → K8s: runtime backend · Daemon can manage boxes on Kubernetes.
- Daemon → Apps: app control · Daemon coordinates apps, routes, buildpacks, and proxies.
- Daemon → Secrets: secret ops · Daemon reconciles and serves encrypted secrets.
- Daemon → Audit: audit trail · Daemon emits append-only audit events.
- Daemon → Net Policy: enforces policy · Daemon applies network policy and enforcement hooks.
- Daemon → Traffic: measures flows · Daemon records traffic and connection accounting.
- Daemon → API Surface: serves API · Daemon exposes protobuf-defined API surfaces.
- API Surface → Generated PB: generated handlers · Generated gRPC and REST handlers implement the canonical contract.
- CLI → Daemon: operator control · Operator CLI and server entrypoints share the same service logic.
- CLI → MCP API: mcp tools · CLI-related MCP workflows reuse the same MCP tool plumbing.
- Agent Box → MCP API: stdio tools · The in-box MCP server exposes file, shell, and directory tools over stdio.
- Agent Box → Auth: root boundary · Constrained root and tenant scoping are enforced around agent-box operations.
- Agent Runtime → MCP API: drives agents · Agent runtime sits beside the platform and orchestrates model-backed execution.
- Web UI → API Surface: consumes api · Web UI reads platform APIs and event streams.
- Daemon → Agent Box: tenant boxes · Daemon provisions and manages the persistent boxes used by tenants.