footprintai/containarium

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.