FootprintAI/Containarium

Containarium – an Open‑Source Runtime for AI Agents

What it is – A self‑hosted platform that gives each AI‑agent its own isolated Linux container (LXC or Kubernetes) that can be reached over SSH. The container runs a tiny MCP (Message‑Control‑Protocol) server (agent‑box) so the agent can issue safe, bounded commands like shell_exec, read_file, write_file, etc. The host side also runs an MCP server that creates, lists, deletes, and exposes containers. All communication is JWT‑authenticated and can be fronted by a “sentinel” VM that terminates TLS and routes SSH/HTTPS to the right backend box.

Why it matters – AI agents (Claude, Cursor, Gemini, custom MCP clients) need a place to compile code, install dependencies, run tests, and serve web apps without polluting the developer’s laptop or a shared Kubernetes cluster. Containarium provides:

• Persistence – containers survive across agent runs.
• Strong isolation – each tenant gets its own network namespace, no kube‑apiserver token, and eBPF egress policies.
• Real Linux environment – full systemd, GPU passthrough, ZFS snapshots, etc.
• Self‑hosting – runs on a cheap Ubuntu VM, on‑prem hardware, or any cloud, unlike SaaS‑only sandboxes.

Core components

Component	Role
agent‑box (in‑container MCP server)	Executes safe file‑system and shell operations inside the container.
platform MCP server	Manages containers (create, start, stop, expose ports, metrics).
containarium CLI	User‑facing tool that talks to the platform MCP and generates SSH configs.
Sentinel (sshpiper + Caddy)	Always‑on VM that routes SSH and HTTPS to the correct backend container, giving public hostnames and TLS termination.
Security layers	JWT auth, optional image‑digest verification, envelope‑encrypted secrets via KMS, eBPF egress policies.

Typical workflow

1. Install the daemon on an Ubuntu VM (curl … | sudo bash).
2. Create a box: containarium quickstart alice – builds an LXC container, creates an SSH key, writes ~/.containarium/ssh_config, and wires the box into the agent’s MCP config.
3. Connect via SSH: ssh alice hostname.
4. Install an agent inside the box: containarium code install alice (places agent‑box and Claude Code, for example).
5. Run code: containarium code run alice --prompt "add a health endpoint" – the agent executes inside the container, logs are streamed, and you can re‑attach later.
6. Expose a service: containarium expose-port alice --container-port 8080 --domain blog.example.com – Caddy on the sentinel routes traffic to the container.

Who would use it –

• Teams that want to run autonomous coding agents on their own infrastructure.
• Companies needing GPU‑enabled, persistent sandboxes with strict isolation.
• Developers who want a reproducible environment that can be reached from anywhere via SSH and can serve public web apps.

Where to start – Follow the Quick start section in the README: a fresh Ubuntu 24.04 VM, run the installer, containarium quickstart <name>, sync the SSH config, and install an agent. The repo also provides docs for multi‑pool deployments, security hardening, and integrations (e.g., the pi dev‑environment).

License & community – Apache 2.0, Go 1.25 codebase, public MCP server badges, and a live demo site.