Skip to content
Back to search

Containarium

Open-source agent runtime — SSH-native isolation, eBPF egress policy, Kubernetes + LXC backends, GPU passthrough, MCP-native CLI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/FootprintAI/Containarium with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/FootprintAI/Containarium'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/footprintai--containarium/badge.svg)](/listings/footprintai--containarium)

HTML

<a href="/listings/footprintai--containarium"><img src="/api/listings/footprintai--containarium/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

One path, three steps, with a check at the end of each. You're done when a box exists, `ssh alice` gets you a shell in it, and your agent can run commands inside it.

**Before you start:** a fresh Ubuntu 24.04 VM you can `sudo` on (see [System requirements](#system-requirements)). You need Containarium **v0.96.0 or later**; the installer fetches the latest release. `sudo` is only needed to run the installer and to read the admin token. Every other command runs as your normal user and goes through the daemon's API.

1. Install, then create your first box

On the VM:

curl -fsSL https://containarium.dev/install.sh | sudo bash

✅ **Check:** the daemon is running and the CLI is on your `PATH`.

systemctl is-active containarium   # → active
containarium version               # → v0.96.0 or later

Point the CLI at the local daemon, using the admin token the installer saved, and create a box called `alice`:

export CONTAINARIUM_HTTP=true
export CONTAINARIUM_SERVER=http://localhost:8080
export CONTAINARIUM_TOKEN="$(sudo cat /etc/containarium/admin.token)"

containarium quickstart alice --no-mcp

`quickstart` does four things: it creates the box; it reuses your `~/.ssh` key or generates a managed one (`~/.ssh/containarium_ed25519`); it writes `~/.containarium/ssh_config`; and it adds the single `Include ~/.containarium/ssh_config` line to `~/.ssh/config`. Passing `--no-mcp` leaves the agent wiring for step 3. It's safe to run again.

✅ **Check:** `quickstart` ends with `✓ quickstart complete`, and the box is listed as running.

containarium list   # → a row for alice-container, STATUS running

2. Connect to the box

Choose the variant that matches where you're typing.

**Variant A: on the VM.** This works on a fresh install. Step 1 already wrote the config. Re-sync whenever your boxes change:

containarium ssh-config sync --identity ~/.ssh/containarium_ed25519
# leave out --identity if quickstart reused your own ~/.ssh key

✅ **Check:**

ssh alice hostname   # → alice-container

**Variant B: from your laptop. Needs a sentinel or `--ssh-host`.** A fresh single-VM install doesn't advertise a public SSH host. A laptop-side sync would therefore write the box's private bridge IP, and `ssh alice` couldn't connect. Use this variant when your deployment has a [sentinel](#sentinel--sshpiper--caddy--proxy-protocol) or the daemon runs with `--ssh-host`. Making this work out of the box is tracked in [#2249](https://github.com/FootprintAI/Containarium/issues/2249).

# On your laptop: install the client only.
curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install-cli.sh | sudo bash

# Reach the daemon's API through an SSH tunnel to the VM.
ssh -fN -L 8080:localhost:8080 <you>@<vm-host>
export CONTAINARIUM_HTTP=true
export CONTAINARIUM_SERVER=http://localhost:8080
export CONTAINARIUM_TOKEN="$(ssh <you>@<vm-host> sudo cat /etc/containarium/admin.token)"

# Leave out --sentinel when the daemon runs with --ssh-host.
containarium ssh-config sync --sentinel <sentinel-host>

Then make `Include ~/.containarium/ssh_config` the first line of your laptop's `~/.ssh/config`. Your laptop's public key also has to be on the box (see `containarium collaborator add --help`).

✅ **Check:**

containarium ssh-config show --sentinel <sentinel-host> | grep '^Host '   # → Host alice

3. Wire your agent to the box

Your agent reaches the box through `agent-box`, an MCP server that runs inside it. `code install` puts it there, along with Claude Code. Run it on the VM, in the same shell as step 1:

containarium code install alice

✅ **Check:** the install prints `agent-box installed at …/.local/bin/agent-box`, and the binary is there:

ssh alice 'test -x ~/.local/bin/agent-box && echo agent-box ready'   # → agent-box ready

Then register the box with your agent, on the machine where the agent

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,094 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Containarium — Agent Runtime
  2. > **Open-source agent runtime** · SSH-native isolation · eBPF egress policy · Kubernetes + LXC · MCP-native CLI · GPU passthrough
  3. **The open-source, self-hostable agent runtime for AI agents.**
  4. Each agent gets a persistent, SSH-reachable box in an unprivileged container, with an opt-in per-tenant eBPF egress policy, audit-logged denials, and a model gateway that keeps provider API keys out of the box. What is on by default, and what each claim rests on, is in [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md).
  5. Bring your own agent — Cursor, Claude Code, OpenCode, your own MCP client.
  6. We run the box.
  7. ```
  8. agent: "create me a sandbox called 'blog'" → containarium create
  9. agent: "wire up SSH so I can reach it" → containarium ssh-config sync
  10. agent: "install Caddy on :8080 inside the box" → shell_exec (via agent-box MCP)
  11. agent: "expose that on blog.example.com" → containarium expose-port
  12. curl https://blog.example.com → hello world
  13. ```
  14. [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
  15. [![Go](https://img.shields.io/badge/go-1.26-00ADD8.svg)](go.mod)
  16. [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/FootprintAI/Containarium/badge)](https://scorecard.dev/viewer/?uri=github.com/FootprintAI/Containarium)
  17. [![Containarium MCP server](https://glama.ai/mcp/servers/FootprintAI/Containarium/badges/score.svg)](https://glama.ai/mcp/servers/FootprintAI/Containarium)
  18. [![Containarium MCP server](https://glama.ai/mcp/servers/FootprintAI/Containarium/badges/card.svg)](https://glama.ai/mcp/servers/FootprintAI/Containarium)
  19. [![Stack Fingerprint](https://stackfingerprint.vercel.app/api/card?repo=FootprintAI/Containarium&theme=midnight&layout=classic)](https://stackfingerprint.vercel.app/?repo=FootprintAI/Containarium)
  20. [![Containarium quickstart: one command turns a fresh box into SSH + a wired agent + a live HTTPS app](docs/images/quickstart.gif)](https://youtu.be/IBDDD_tb8FY)
  21. 🌐 **Project site:** [containarium.dev](https://containarium.dev) · 🎬 **55s demo:** [youtu.be/IBDDD_tb8FY](https://youtu.be/IBDDD_tb8FY) · 🚀 **Live app:** [helloworld.demo.containarium.dev](https://helloworld.demo.containarium.dev)
  22. ---
  23. ## Choose your path
  24. | Path | You end up with | Go to |
  25. |------|-----------------|-------|
  26. | **Hosted cloud** | a box you can `ssh` into with your agent wired to it, no server to run | [Sign up at cloud.containarium.dev](https://cloud.containarium.dev) |
  27. | **Self-host on a VM** | the same, on your own Ubuntu VM (about 5 minutes) | [Quick start](#quick-start) |
  28. | **See the end result** | a live app served from a box, which is what you end up with | [helloworld.demo.containarium.dev](https://helloworld.demo.containarium.dev) |
  29. ---
  30. ## Why an agent runtime?
  31. AI agents are increasingly the primary user of dev infrastructure. They
  32. want to build, install, deploy, and verify — not on the human's laptop
  33. (too noisy, too risky, too local) but on a persistent runtime that's:
  34. - **Persistent**: state survives between agent runs.
  35. - **Separate from your machine**: a misbehaving install doesn't touch your laptop or your cluster. (Tenant-to-tenant isolation is not on by default; see [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md).)
  36. - **Real**: a full Linux environment with `systemd`, real networking,
  37. and the ability to host things on the open internet.
  38. - **Driven by structured tools**: not by an agent typing commands into a
  39. TTY hoping nothing scrolls off-screen, but by MCP — typed,
  40. bounded, safe.
  41. - **Blast-radius-bounded**: the agent holds an SSH key, not a
  42. kube-apiserver token. It can't reach the cluster control plane, the
  43. host OS, or other tenants' boxes.
  44. That's the runtime Containarium gives you. It runs as a self-hosted
  45. platform on LXC or Kubernetes, exposes its admin surface over MCP, and
  46. ships a second MCP server that lives *inside* the box so the agent can
  47. `shell_exec` and edit files directly.
  48. You bring the agent. We run the box.
  49. ---
  50. ## Quick start
  51. One path, three steps, with a check at the end of each. You're done when a
  52. box exists, `ssh alice` gets you a shell in it, and your agent can run
  53. commands inside it.
  54. **Before you start:** a fresh Ubuntu 24.04 VM you can `sudo` on (see
  55. [System requirements](#system-requirements)). You need Containarium
  56. **v0.96.0 or later**; the installer fetches the latest release. `sudo` is
  57. only needed to run the installer and to read the admin token. Every other
  58. command runs as your normal user and goes through the daemon's API.
  59. ### 1. Install, then create your first box
  60. On the VM:
  61. ```bash
  62. curl -fsSL https://containarium.dev/install.sh | sudo bash
  63. ```
  64. ✅ **Check:** the daemon is running and the CLI is on your `PATH`.
  65. ```bash
  66. systemctl is-active containarium # → active
  67. containarium version # → v0.96.0 or later
  68. ```
  69. Point the CLI at the local daemon, using the admin token the installer
  70. saved, and create a box called `alice`:
  71. <!-- The published installer (https://containarium.dev/install.sh) now carries
  72. `--quickstart <name>` (checked 2026-10-15; #2244 is closed). Flip this
  73. block to the one-liner (`… | sudo bash -s -- --quickstart alice`) once a
  74. fresh-VM run of it has been recorded — not before. -->
  75. ```bash
  76. export CONTAINARIUM_HTTP=true
  77. export CONTAINARIUM_SERVER=http://localhost:8080
  78. export CONTAINARIUM_TOKEN="$(sudo cat /etc/containarium/admin.token)"
  79. containarium quickstart alice
  80. ```
  81. `quickstart` creates the box, reuses your `~/.ssh` key or generates a
  82. managed one (`~/.ssh/containarium_ed25519`), writes
  83. `~/.containarium/ssh_config`, adds the single
  84. `Include ~/.containarium/ssh_config` line to `~/.ssh/config`, and wires
  85. the box into your agent's MCP config (Claude Code by default). It's safe
  86. to run again, including to repair an older quickstart's MCP command.
  87. ✅ **Check:** `quickstart` ends with `✓ quickstart complete`, and the box is
  88. listed as running.
  89. ```bash
  90. containarium list # → a row for alice-container, STATUS running
  91. ```
  92. ### 2. Connect to the box
  93. Choose the variant that matches where you're typing.
  94. **Variant A: on the VM.** This works on a fresh install. Step 1 already
  95. wrote the config. Re-sync whenever your boxes change:
  96. ```bash
  97. containarium ssh-config sync --identity ~/.ssh/containarium_ed25519
  98. # leave out --identity if quickstart reused your own ~/.ssh key
  99. ```
  100. ✅ **Check:**
  101. ```bash
  102. ssh alice hostname # → alice-container
  103. ```
  104. **Variant B: from your laptop.** On a single VM, `ssh-config sync` adds a
  105. `ProxyJump` through the VM's per-user jump account when the daemon doesn't
  106. advertise `ssh_host`. If the API is reached directly, the jump host defaults
  107. to the API hostname, on SSH port 22. With the API tunnel below, name the
  108. actual VM with `--jump-host` (use `<vm-host>:<ssh-port>` for a custom SSH port).
  109. Deployments with a [sentinel](#sentinel--sshpiper--caddy--proxy-protocol) can
  110. use `--sentinel <sentinel-host>` instead; a daemon's `--ssh-host` still takes
  111. precedence over the jump route.
  112. ```bash
  113. # On your laptop: install the client only.
  114. curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install-cli.sh | sudo bash
  115. # Reach the daemon's API through an SSH tunnel to the VM.
  116. ssh -fN -L 8080:localhost:8080 <you>@<vm-host>
  117. export CONTAINARIUM_HTTP=true
  118. export CONTAINARIUM_SERVER=http://localhost:8080
  119. export CONTAINARIUM_TOKEN="$(ssh <you>@<vm-host> sudo cat /etc/containarium/admin.token)"
  120. containarium ssh-config sync --jump-host <vm-host>
  121. ```
  122. Then make `Include ~/.containarium/ssh_config` the first line of your
  123. laptop's `~/.ssh/config`. Use the key whose public half was supplied when
  124. creating the box: that key is authorized on both the box and its VM jump
  125. account. Add `--identity ~/.ssh/<your-private-key>` to sync if needed; it
  126. applies to both SSH connections.
  127. ✅ **Check:**
  128. ```bash
  129. ssh alice-container hostname # → alice-container
  130. ```
  131. ### 3. Wire your agent to the box
  132. Your agent reaches the box through `agent-box`, an MCP server that runs
  133. inside it. `code install` puts it there, along with Claude Code. Run it on
  134. the VM, in the same shell as step 1:
  135. ```bash
  136. containarium code install alice
  137. ```
  138. ✅ **Check:** the install prints `agent-box installed at …/.local/bin/agent-box`,
  139. and the binary is there:
  140. ```bash
  141. ssh alice 'test -x ~/.local/bin/agent-box && echo agent-box ready' # → agent-box ready
  142. ```
  143. On the machine where your agent runs, `quickstart` wires the MCP config
  144. automatically. Step 1 already did this for Claude Code on the VM. If your
  145. agent runs on your laptop, run this there using the API connection from
  146. step 2; it reuses the existing box:
  147. ```bash
  148. containarium quickstart alice --agent claude
  149. # For Gemini or Codex, use --agent gemini or --agent codex instead.
  150. ```
  151. For Cursor, add the server to `~/.cursor/mcp.json` manually:
  152. ```jsonc
  153. {
  154. "mcpServers": {
  155. "containarium-box": {
  156. "command": "ssh",
  157. "args": ["alice", "sh -c 'PATH=\"$HOME/.local/bin:/usr/local/bin:$PATH\" exec agent-box'"]
  158. }
  159. }
  160. }
  161. ```
  162. This command sets the box's `PATH` for non-interactive SSH and supports
  163. both user-level and system-wide installs of `agent-box`.
  164. ✅ **Check:** your agent lists `containarium-box` as a connected MCP server
  165. (in Claude Code, `claude mcp list`). Asking it to *"run `uname -a` in the
  166. box"* returns a Linux kernel line from `alice-container`. It now has
  167. `shell_exec`, `read_file`, `write_file`, `list_directory`, `move_file` and
  168. `delete_file` inside the box.
  169. **That's your first box.** Next:
  170. [run the agent on the box](#run-the-agent-on-the-box) ·
  171. [run pi inside the box](#run-pi-inside-the-box) ·
  172. [put the box on a public hostname](#put-the-box-on-a-public-hostname) ·
  173. [build a site in one command](#build-a-site-in-one-command).
  174. ---
  175. ## After your first box
  176. ### Run the agent on the box
  177. `code install` (step 3) already put Claude Code on the box. It installs
  178. **no credential**: sign-in goes through Anthropic's own flow, never through
  179. us. Choose one of these, once:
  180. ```bash
  181. # interactive: sign in inside the box (device code)
  182. ssh alice
  183. claude
  184. # or headless: your own key in the "env" block of ~/.claude/settings.json on the box
  185. # {"env": {"ANTHROPIC_API_KEY": "<your key>"}}
  186. ```
  187. Then:
  188. ```bash
  189. containarium code run alice --prompt "add a health endpoint and run the tests"
  190. ```
  191. `code run` streams output to your terminal as it's produced, but it isn't a
  192. pipe. The run is detached on the box and its output is captured to a log;
  193. your terminal is a *resumable reader* over that log. Close your laptop, lose
  194. wifi, press Ctrl-C: the run keeps going, and `containarium code attach alice`
  195. picks the stream back up **byte-exact**, with nothing missing and nothing
  196. repeated.
  197. ```bash
  198. containarium code attach alice # reconnect; replays what you missed
  199. containarium code status alice # liveness, and the exit code once it finishes
  200. containarium code stop alice # reap it; the log stays readable
  201. ```
  202. The difference from the MCP wiring in step 3 is where the agent runs. There,
  203. the agent is on your machine and reaches into the box. Here, the agent *is*
  204. on the box, so the work survives your machine sleeping, and the tests run
  205. next to the code instead of over a network hop.
  206. ### Run pi inside the box
  207. If your agent has no MCP client, run it *inside* the box instead. See
  208. [docs/integrations/pi.md](docs/integrations/pi.md) for the
  209. [pi](https://pi.dev) walkthrough (installs, keys, code sync, sessions).
  210. ### Put the box on a public hostname
  211. ```bash
  212. containarium expose-port alice \
  213. --container-port 8080 \
  214. --domain blog.example.com
  215. ```
  216. Caddy on the sentinel terminates TLS for `blog.example.com` and forwards to
  217. `alice-container:8080`. `curl https://blog.example.com` then hits whatever
  218. `alice` is serving on port 8080.
  219. ### Build a site in one command
  220. Run from your laptop against a server you can reach (see step 2, variant B),
  221. `quickstart` does steps 1–3 in one go: it creates the box and wires SSH and
  222. your agent (`claude`, `gemini` or `codex`). With `--prompt` it also exposes
  223. `--domain` and launches your local agent on the build:
  224. ```bash
  225. containarium quickstart alice --server <your-server> \
  226. --prompt "a coffee-shop landing page" --domain coffee.example.com
  227. ```
  228. `containarium quickstart --help` lists every option.
  229. ---
  230. ## The four primitives
  231. Every action in Containarium has a CLI verb (canonical) AND an MCP tool
  232. (thin wrapper that delegates to the same Go function). See
  233. [CLAUDE.md](CLAUDE.md) for the convention.
  234. ### `agent-box` — in-the-box MCP server
  235. Runs inside every container. Reached over stdio (typically wrapped by
  236. SSH on the client side). Exposes Linux-native operations:
  237. | Tool | What it does |
  238. |---|---|
  239. | `shell_exec` | Run a shell command, capture stdout/stderr/exit, bounded by timeout (default 30s, max 10min) and 256 KiB output cap |
  240. | `read_file` | Byte range OR `head=N` lines OR `tail=N` lines |
  241. | `write_file` | Atomic write with `mkdirp` (temp + rename) |
  242. | `list_directory` | Type/size/mtime, hidden filtering |
  243. | `move_file` | Atomic rename with `mkdirp` on destination |
  244. | `delete_file` | Single-file remove (refuses directories so recursive deletes go via `shell_exec` where blast radius is explicit) |
  245. Resources (read-only data the agent fetches via MCP `resources/read`):
  246. | URI | What it returns |
  247. |---|---|
  248. | `containarium://ci-context` | JSON metadata about the current CI run (PR number, commit SHA, failing test, etc.) when the box was kept alive by the FootprintAI/containarium-run GitHub Action after a failed CI run. Returns `{"available": false}` on non-CI boxes so callers never have to special-case errors. |
  249. | `containarium://ci-prompt` | Static markdown playbook telling agents how to debug a failing CI run inside this box (what to read first, how to iterate, what not to do). Same body on every box; pair with `ci-context` for the per-run data. |
  250. Optional sandbox: when `AGENTBOX_ROOT` is set, every file-ops path is
  251. resolved against that root with a boundary-aware prefix check. Default
  252. unset = no constraint. See
  253. [`internal/agentbox/`](internal/agentbox/) for the Go implementation.
  254. ### `mcp-server` — platform MCP server
  255. Runs on the host. Exposes the platform's outside-the-box operations as
  256. MCP tools — about a hundred of them, one per CLI verb: container lifecycle
  257. (`create_container`, `list_containers`, `start_container`,
  258. `stop_container`, `delete_container`, `resize_container`), networking
  259. (`expose_port`, `sync_ssh_config`, passthrough routes), coding-agent runs
  260. (`code_run`, `code_attach`, `code_status`, `code_stop`), secrets, backups,
  261. recipes, security scans, tracker connections, and `get_metrics` /
  262. `get_system_info`. A token's scopes decide which ones a client sees. See
  263. [`cmd/mcp-server/`](cmd/mcp-server/) and
  264. [`internal/mcp/`](internal/mcp/) for the catalog.
  265. ### `containarium` CLI
  266. Same surface as the platform MCP, plus deeper administration. The verbs
  267. this README uses (the CLI has about ninety — `containarium --help` lists
  268. them all):
  269. ```
  270. containarium quickstart Create a box, wire SSH + your agent, optionally build a site
  271. containarium create Create a new container
  272. containarium list List all containers
  273. containarium wake / sleep Start a stopped box / stop a running one
  274. containarium stop --hold Stop a box and keep it stopped until an explicit `wake`
  275. containarium delete Delete a container
  276. containarium code Run a coding agent ON a box (install / run / attach / logs / runs / status / stop / egress-policy)
  277. containarium expose-port Expose container:port on a public hostname
  278. containarium ssh-config Generate self-contained ssh_config (show / sync)
  279. containarium route Manage proxy routes (low-level)
  280. containarium passthrough-route Manage TCP/UDP passthrough routes (daemon API)
  281. containarium token Issue, inspect, refresh and revoke JWT tokens
  282. containarium login / connect Device-flow sign-in to a server; open a shell on a box with that token
  283. containarium info Container or system info
  284. containarium version Print version
  285. ```
  286. Host-side verbs (`daemon`, `sentinel`, `passthrough`, `audit`, `doctor`,
  287. …) live in `containariumd` — see [Two binaries](#two-binaries-containarium-vs-containariumd).
  288. Run `containarium <verb> --help` for full options.
  289. ### Sentinel — sshpiper + Caddy + PROXY-protocol
  290. The sentinel is a tiny always-on VM (e2-micro on GCP free tier works)
  291. that:
  292. - Receives SSH on port 22 (sshpiper routes to the right backend by
  293. username).
  294. - Receives HTTPS on 443 (Caddy with TLS-passthrough or
  295. PROXY-protocol-aware forwarding to backend Caddy).
  296. - Survives spot-VM termination on the backend with a maintenance page.
  297. - Holds the static IP / DNS A-record so backends can be ephemeral.
  298. See [docs/SENTINEL-DESIGN.md](docs/SENTINEL-DESIGN.md) for the full
  299. design.
  300. ---
  301. ## Architecture
  302. ```
  303. Agent (Cursor / Claude Code / OpenCode)
  304. │
  305. │ JWT (access; tt=access, jti, scopes)
  306. │ MCP over stdio ──┐
  307. │ │ ┌── refresh ──> POST /v1/tokens/refresh
  308. v ▼ │ (single-use; old jti revoked)
  309. ssh user@box → sshpiper → agent-box (in container)
  310. │
  311. │ HTTPS (mTLS upstream; PROXY-protocol v2)
  312. v
  313. Sentinel (e2-micro, always-on)
  314. ├── sshpiper (port 22) : routes by username; fail2ban per-user
  315. ├── Caddy + PROXY-protocol (443) : routes by hostname / SNI suffix
  316. └── /wake/ source-IP allowlist : trusted-proxy only
  317. │
  318. v
  319. +-------------------------------------------------+
  320. | Backend VM (spot or bare-metal GPU node) |
  321. | |
  322. | Incus (LXC) ── containers |
  323. | ├── alice-container : SSH + agent-box |
  324. | │ └── /run/secrets/* : tmpfs, 0440 alice |
  325. | └── bob-container : ZFS-backed storage |
  326. | |
  327. | Containarium daemon |
  328. | ├── JWT auth (iss/aud/jti/scopes) |
  329. | ├── Admin RBAC + container-owner authz |
  330. | ├── Image-digest gate (REQUIRE + VERIFY) |
  331. | ├── Secrets ── Postgres (envelope-encrypted) |
  332. | │ │ |
  333. | │ v |
  334. | │ KMS ── Vault Transit / GCP KMS |
  335. | │ (master key retirable post-cutover)
  336. | └── Audit log ── Postgres + SHA-256 hash |
  337. | chain (verify CLI) |
  338. +-------------------------------------------------+
  339. ```
  340. A single sentinel can front multiple backend VMs — a "pool" — and a
  341. single deployment can run multiple pools (each with its own backends). See
  342. [docs/MULTI-POOL.md](docs/MULTI-POOL.md).
  343. **Security control surface** (all opt-in via env, default-off for
  344. upgrade safety; see [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](docs/security/OPERATOR-SECURITY-RUNBOOK.md)):
  345. | Env var | Layer | Effect |
  346. | --- | --- | --- |
  347. | `CONTAINARIUM_REQUIRE_IMAGE_DIGEST=true` | API | refuse images without `@sha256:<64hex>` | <!-- claim-row: Image-registry allow-list and digest verification. -->
  348. | `CONTAINARIUM_VERIFY_IMAGE_DIGEST=true` | API | verify digest against the registry index (pre- + post-pull) |
  349. | `CONTAINARIUM_ALLOWED_IMAGE_REGISTRIES` | API | restrict which simplestreams remotes the daemon will pull from |
  350. | `CONTAINARIUM_KMS_BACKEND={none,inproc,vault,gcp}` | Secrets | envelope-encrypt DEKs through an external KMS |
  351. | `CONTAINARIUM_REQUIRE_ENVELOPE=true` | Secrets | refuse legacy master-key-only rows (Phase E retirement gate) |
  352. | `CONTAINARIUM_POSTGRES_URL_FILE` / `_PASSWORD_FILE` | Secrets | DB creds from disk rather than env |
  353. | `CONTAINARIUM_WAKE_TRUSTED_PROXIES` | Sentinel | source-IP allowlist for `/wake/` |
  354. | `OTEL_BEARER_REQUIRED=true` | Telemetry (collector-side; set on the OTel collector, not the daemon) | collector rejects un-bearered OTLP submissions |
  355. ---
  356. ## How it's different
  357. ### vs. SaaS-only sandboxes (e2b, Modal, Replit)
  358. These give you sandboxes for AI agents, but only as hosted SaaS:
  359. - **Self-hostability**: Containarium runs on your own infrastructure
  360. (a $5 VM, your homelab, your enterprise data center). e2b, Modal,
  361. and Replit are SaaS-only — your code, your data, and your customers
  362. go through their compute.
  363. - **License**: Apache 2.0, no CLA. Fork it, sell it, run it.
  364. - **Surface**: full Linux containers with `systemd`, real network
  365. namespaces, GPU passthrough. Not a process-per-call sandbox.
  366. - **Transport**: MCP-native from day one, not a custom SDK with MCP
  367. bolted on.
  368. ### vs. Docker AI Sandboxes (`sbx`)
  369. Docker's `sbx run claude` and Containarium both call themselves
  370. "AI sandboxes," but they sit on opposite ends of the same spectrum:
  371. - **Locality**: `sbx` runs the sandbox on the developer's laptop
  372. (microVM, host-isolation). Containarium runs the sandbox on a VM
  373. you host (LXC, multi-tenant, public-internet reachable via the
  374. sentinel).
  375. <!-- claim-exempt: describes another product's locality, not a Containarium claim -->
  376. - **Persistence**: `sbx` is session-shaped (workspace mount, no
  377. documented "give me a box that survives reboot and has a
  378. hostname"). Containarium containers persist indefinitely, with
  379. ZFS snapshots and 30-day retention.
  380. - **Public reach**: `containarium expose-port alice --domain
  381. blog.example.com` is one verb. `sbx` is laptop-local; no
  382. public-hostname story.
  383. - **Agent surface**: `sbx` is CLI-first (`sbx run <agent>`).
  384. Containarium is MCP-native — two MCP servers (in-the-box
  385. `agent-box` + platform `mcp-server`) plus the same surface via
  386. CLI, SSH, REST/gRPC, and a web UI.
  387. - **License**: `sbx` CLI is free; team policy (Docker Admin Console)
  388. is a paid subscription. Containarium is Apache 2.0 — including
  389. the audit log, RBAC, KMS integrations, and everything else on
  390. this page.
  391. If you're stopping an agent from `rm -rf`-ing the laptop it's
  392. running on, `sbx` is the lighter tool. If you're giving your agent
  393. (or your customer's agent) a persistent Linux box on the public
  394. internet, Containarium is the shape.
  395. ### vs. OSS Kubernetes agent runtimes (agent-sandbox, OpenShell)
  396. [`kubernetes-sigs/agent-sandbox`](https://github.com/kubernetes-sigs/agent-sandbox)
  397. and [`NVIDIA/OpenShell`](https://github.com/NVIDIA/OpenShell) are the
  398. closest open-source peers on Kubernetes:
  399. - **SSH-native vs. exec-based**: both agent-sandbox and OpenShell reach
  400. the sandbox via `kubectl exec` or a proprietary client, which requires
  401. the agent to hold a kube-apiserver token or cluster credentials.
  402. Containarium reaches the pod over SSH through sshpiper — the agent has
  403. no path to the cluster control plane at all.
  404. - **MCP-native**: agent-sandbox and OpenShell expose REST APIs or custom
  405. SDKs. Containarium's `agent-box` MCP server runs *inside* the box,
  406. reachable over SSH stdio — any MCP-speaking agent (Claude Code, Cursor,
  407. OpenCode) works with zero client library.
  408. - **LXC + K8s, one CLI**: Containarium runs on either Incus/LXC or
  409. Kubernetes behind the same `containarium` CLI and `--runtime` flag. You
  410. switch backends without changing anything for the agent.
  411. - **eBPF egress policy**: Containarium can enforce per-tenant egress
  412. allowlists at the kernel level via TC_INGRESS eBPF programs once an
  413. operator arms them (opt-in; see [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md)).
  414. agent-sandbox has NetworkPolicy; OpenShell has eBPF but is
  415. NVIDIA-stack-specific. Neither offers a portable, per-tenant eBPF
  416. allowlist across LXC and K8s backends.
  417. ### vs. dev environment platforms (Codespaces, Gitpod, Coder)
  418. Those are persistent IDEs. Containarium is a persistent **box** —
  419. agent-driven, not developer-driven, no IDE assumption, SSH-as-the-API:
  420. - Containarium environments are reached by SSH and MCP. Any IDE works
  421. (Vim, JetBrains Remote, VS Code Remote, Cursor's remote dev — your
  422. call).
  423. - Cost: no per-hour billing in the OSS path. Self-host costs are just
  424. your underlying VM.
  425. - Persistence: containers survive indefinitely; Codespaces auto-delete
  426. after inactivity.
  427. ### vs. application container platforms (Docker, Kubernetes)
  428. LXC is a **system** container, not an application container. Each
  429. container has `systemd`, a real init, real users, real package managers,
  430. real `sudo`. You can run Docker *inside* a Containarium container; the
  431. reverse isn't really a thing.
  432. If your agent is going to `apt install` half a Linux distro, edit
  433. config files in `/etc`, run a database, and reboot — LXC is the right
  434. shape. If your agent runs a single Python process, Docker or Modal is
  435. fine.
  436. It isn't either/or: Containarium can run a box *as a pod* in a
  437. Kubernetes cluster you already operate — same SSH-native agent contract,
  438. no kube-apiserver token in the agent's hands. Switch with
  439. `--runtime=k8s`. See the **Kubernetes backend** section below.
  440. ---
  441. ## What's in the box
  442. Beyond the agent-native primitives, Containarium ships:
  443. ### Multi-OS
  444. - **Ubuntu 24.04 LTS** (default)
  445. - **Rocky Linux 9** (dev/test)
  446. - **RHEL 9** (production)
  447. - **Windows Server VMs** via QEMU/KVM with RDP — see
  448. [docs/WINDOWS-VM-SETUP.md](docs/WINDOWS-VM-SETUP.md)
  449. ### GPU passthrough
  450. For ML/AI agent workflows. Works with NVIDIA RTX 3090, RTX 4090, and
  451. similar. PCI-level passthrough so the container sees the GPU directly.
  452. Tested on bare-metal GPU nodes connected to the sentinel via tunnel.
  453. ### Multi-backend
  454. A single sentinel can front:
  455. - **GCP spot VMs**: cost-effective cloud backends with auto-recovery
  456. on preemption.
  457. - **Bare-metal GPU nodes**: any Linux box you can SSH to; reaches the
  458. sentinel via outbound tunnel.
  459. - **Windows VMs**: live alongside Linux backends.
  460. All containers from all backends appear in a single unified API.
  461. ### Kubernetes backend (experimental)
  462. Beyond the LXC/Incus backend, Containarium can run a box as a **pod in a
  463. Kubernetes cluster you already operate** — reached over SSH exactly like
  464. an LXC box, so an agent can't tell which substrate it landed on. The
  465. daemon reconciles a per-tenant namespace + StatefulSet + headless Service
  466. + default-deny NetworkPolicy, and programs the sshpiper gateway (the
  467. `Pipe` CRD) so `ssh <tenant>@<gateway>` routes to the right pod.
  468. What the NetworkPolicy does and does not guarantee is in
  469. [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md).
  470. <!-- claim-row: Kubernetes boxes get a default-deny NetworkPolicy. -->
  471. The pitch isn't "another way to run pods" — it's giving an agent a
  472. hardened, SSH-native foothold in your cluster **without handing it a
  473. kube-apiserver token**: the box runs with `automountServiceAccountToken:
  474. false` and satisfies the `restricted` Pod Security profile. Compare this
  475. to `kubectl exec`-based runtimes where the agent necessarily holds cluster
  476. credentials.
  477. **Runtime selection** (no recompile needed):
  478. ```bash
  479. # LXC/Incus (default)
  480. containariumd daemon
  481. # Kubernetes — uses in-cluster config or KUBECONFIG
  482. CONTAINARIUM_RUNTIME=k8s containariumd daemon
  483. # or
  484. containariumd daemon --runtime=k8s
  485. ```
  486. Both backends share the same CLI, MCP tools, JWT auth, and REST/gRPC API.
  487. GPU passthrough is supported on K8s via `nvidia.com/gpu` resource limits.
  488. Local bring-up takes under 5 minutes with `kind` — see
  489. [docs/KIND-QUICKSTART.md](docs/KIND-QUICKSTART.md).
  490. Design, topology, and BYO-cluster integration:
  491. [docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md](docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md).
  492. ### Web UI
  493. A basic dashboard at `/webui/` for users who'd rather not type CLI:
  494. container list, lifecycle controls, metrics, browser-based terminal.
  495. Polished UI is intentionally a cloud-product concern — the OSS web UI
  496. is functional, not opinionated.
  497. ### Persistent storage (ZFS)
  498. Containers survive VM restarts and spot termination. ZFS handles
  499. compression, snapshots (daily by default, 30-day retention), and
  500. checksums.
  501. ### Sentinel HA
  502. The sentinel itself is e2-micro (free tier). It:
  503. - Detects spot preemption in ~10s, serves a maintenance page.
  504. - Restarts spot VMs automatically (~85s total recovery).
  505. - Holds the static IP, so DNS doesn't change as backends rotate.
  506. ### Monitoring & observability
  507. VictoriaMetrics + Grafana auto-provisioned. Per-container CPU,
  508. memory, disk, network. Alerting via webhooks. SSH audit logs per
  509. user (LXC backend; the Kubernetes backend records control-plane API
  510. audit but not in-box SSH sessions — see #1189).
  511. <!-- claim-row: SSH session audit logs per user. -->
  512. ### Security primitives
  513. - **Unprivileged LXC containers**: container root ≠ host root.
  514. - **Per-user proxy accounts**: `/usr/sbin/nologin` on the sentinel,
  515. users can only proxy through to their container.
  516. - **fail2ban per-user**: an attack on Alice's account doesn't ban
  517. Bob.
  518. - **Trivy** image/dependency scanning across backends. **ClamAV** malware scanning is a tenant-run capability (the scan runs inside a box, started by its owner, and the verdict is self-reported); it is being rebuilt in #2631 and is not a platform-wide control today.
  519. - **AppArmor profiles** per container.
  520. - **AGENTBOX_ROOT sandbox** to constrain agent-box file ops at runtime.
  521. **Zero-trust controls** (see [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](docs/security/OPERATOR-SECURITY-RUNBOOK.md); several are opt-in, see [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md) for what is on by default):
  522. - **JWT with `iss` / `aud` / `jti` / `tt` / `scopes`**: 32-byte minimum
  523. secret enforced at startup; refresh tokens are single-use; jti-based
  524. revocation; per-tool MCP scopes propagate to server-side gates.
  525. - **Admin RBAC + per-container ownership** on the API surface; cluster
  526. ops admin-only, container ops owner-only.
  527. - **KMS envelope encryption for tenant secrets** (Vault Transit or GCP
  528. Cloud KMS), with a migration tool and master-key retirement gate.
  529. - **tmpfs `--delivery=file`** for secrets that shouldn't be visible in
  530. `/proc/<pid>/environ`.
  531. - **Audit log with SHA-256 hash chain** + `containariumd audit verify`
  532. (on the host): tamper-evident against an application- or database-level
  533. attacker. An attacker who can write the database can rewrite the chain
  534. consistently; the chain root can be anchored to a file outside the database
  535. (`internal/audit/anchor.go`), which a database credential does not reach, but
  536. a host-root attacker could still edit both.
  537. - **Image-registry allowlist + pre-pull simplestreams digest
  538. verification + post-pull `volatile.base_image` defense-in-depth**
  539. for supply-chain hardening.
  540. - **`SECURITY.md`** with a 90-day coordinated-disclosure window;
  541. `gosec` / `govulncheck` / `trivy` running in CI.
  542. ---
  543. ## CLI reference (essentials)
  544. ### Container lifecycle
  545. ```bash
  546. # Create (Ubuntu 24.04, default)
  547. containarium create alice --ssh-key ~/.ssh/id_ed25519.pub
  548. # Create with options
  549. containarium create ml-dev \
  550. --ssh-key ~/.ssh/id_ed25519.pub \
  551. --gpu 0 \
  552. --stack gpu \
  553. --memory 16GB \
  554. --cpu 4
  555. # Lifecycle
  556. containarium list
  557. containarium info
  558. containarium wake alice # start a stopped box
  559. containarium sleep alice # stop it
  560. containarium stop --hold alice # stop it and hold it: no autostart, no HTTP wake, until `wake`
  561. containarium delete alice
  562. ```
  563. ### Networking
  564. ```bash
  565. # Expose a container port on a public hostname
  566. containarium expose-port alice \
  567. --container-port 8080 \
  568. --domain blog.example.com
  569. # Lower-level route management
  570. containarium route add api.example.com --target 10.0.3.42:3000
  571. containarium route list
  572. containarium route delete api.example.com
  573. # Raw TCP/UDP passthrough via local iptables (on the host, so it's a
  574. # containariumd verb)
  575. containariumd passthrough add --port 50051 \
  576. --target-ip 10.0.3.150 --target-port 50051
  577. # Raw TCP/UDP passthrough via the daemon API (works against a remote box)
  578. containarium passthrough-route add --port 9443 \
  579. --target-ip 10.0.3.150 --target-port 50051 --server <host:port>
  580. containarium passthrough-route list --server <host:port>
  581. containarium passthrough-route remove --port 9443 --server <host:port>
  582. ```
  583. ### SSH config
  584. ```bash
  585. # Print to stdout (preview)
  586. containarium ssh-config show
  587. # Write to ~/.containarium/ssh_config (one-line `Include` to wire in)
  588. containarium ssh-config sync
  589. containarium ssh-config sync --sentinel sentinel.example.com # via sentinel
  590. containarium ssh-config sync --identity ~/.ssh/containarium_ed25519
  591. # From a client machine, against a remote server (the bare form above
  592. # only reaches a local Incus socket)
  593. containarium ssh-config sync --http --server <host:port>
  594. ```
  595. ### Authentication
  596. ```bash
  597. # Issue an access + refresh pair (CLI-only; never exposed via API).
  598. # Access tokens are short-lived (default 15 min) and authenticate the
  599. # API. Refresh tokens are long-lived and single-use — exchange via
  600. # POST /v1/tokens/refresh for a new pair.
  601. containarium token generate \
  602. --username admin \
  603. --roles admin \
  604. --secret-file /etc/containarium/jwt.secret
  605. # Use the access token
  606. curl -H "Authorization: Bearer <access-token>" http://localhost:8080/v1/containers
  607. # Exchange the refresh token for a new pair (same as POST /v1/tokens/refresh;
  608. # the refresh token is the credential, so no --token)
  609. containarium token refresh --refresh-token "$REFRESH" --server <host:port>
  610. # Inspect a token's claims (jti, scopes, expiry, validation)
  611. containarium token inspect <token> --secret-file /etc/containarium/jwt.secret
  612. # Revoke a leaked token by jti (idempotent; reads from `audit query`
  613. # or `token inspect`)
  614. containarium token revoke <jti> --reason "leak_2026_05_22"
  615. containarium token list-revoked
  616. # Mint a least-privilege token for an agent with only the scopes it
  617. # needs — server-side gates enforce this even if the agent ignores
  618. # the filter.
  619. containarium token generate \
  620. --username alice-agent \
  621. --scopes containers:read,containers:write \
  622. --secret-file /etc/containarium/jwt.secret
  623. ```
  624. See [`docs/security/OPERATOR-SECURITY-RUNBOOK.md`](docs/security/OPERATOR-SECURITY-RUNBOOK.md)
  625. for the full token lifecycle, leak-response playbook, and the agent
  626. least-privilege scope catalog.
  627. <!-- claim-exempt: points to the runbook, asserts no property of the product -->
  628. ---
  629. ## Deployment
  630. ### Two binaries: `containarium` vs `containariumd`
  631. Same convention as `docker`/`dockerd` or `incus`/`incusd`: `containarium`
  632. is the CLI you run from your laptop (`create`, `list`, `ssh-config`,
  633. `expose-port`, …); `containariumd` is what runs *on the host* — the
  634. daemon, the sentinel, and every on-host admin verb (`daemon`,
  635. `sentinel`, `service install`, `sync-accounts`, `pool join`, `node`,
  636. `hosting`, `recover`, `doctor`). Install `containarium` wherever you
  637. want to drive the platform from (your laptop, a jump box); install
  638. `containariumd` on every host that runs the daemon or sentinel itself.
  639. A compat symlink (`/usr/local/bin/containarium -> containariumd`) keeps
  640. existing hosts and scripts that still invoke `containarium <daemon verb>`
  641. working during the rollout.
  642. ### Manual install (recommended for getting started)
  643. ```bash
  644. curl -fsSL https://containarium.dev/install.sh | sudo bash
  645. ```
  646. See [`hacks/README.md`](hacks/README.md) for what the script does.
  647. ### Terraform (recommended for production)
  648. ```bash
  649. cd terraform/gce
  650. cp examples/single-server-spot.tfvars terraform.tfvars
  651. vim terraform.tfvars # set project_id, admin_ssh_keys, allowed_ssh_sources
  652. terraform init
  653. terraform apply
  654. ```
  655. See [`terraform/gce/README.md`](terraform/gce/README.md) for variables.
  656. ### System requirements
  657. - **Host OS**: Ubuntu 24.04 LTS or later, or Debian 13 (trixie)
  658. (containers can be any supported OS). Debian 13 has been verified
  659. with the installer; Debian 12 is accepted but untested. The ZFS
  660. kernel module is optional on Debian, where the cloud kernel does not
  661. ship it; disk quotas then need another storage backend.
  662. - **Incus 6.19+** required for Docker-in-LXC support. Ubuntu 24.04's
  663. default repos ship 6.0.0 which has an AppArmor bug
  664. ([CVE-2025-52881](https://ubuntu.com/security/CVE-2025-52881));
  665. use the [Zabbly Incus repository](https://pkgs.zabbly.com/) for
  666. current builds.
  667. <!-- claim-exempt: names a vendor CVE that affects installs, asserts no Containarium property -->
  668. - **ZFS kernel module** (for disk quotas).
  669. - Kernel modules: `overlay`, `br_netfilter`, `nf_nat` (Docker in
  670. containers needs these).
  671. ```bash
  672. # Quick Incus install via Zabbly
  673. curl -fsSL https://pkgs.zabbly.com/key.asc | \
  674. sudo gpg --dearmor -o /usr/share/keyrings/zabbly-incus.gpg
  675. echo 'deb [signed-by=/usr/share/keyrings/zabbly-incus.gpg] \
  676. https://pkgs.zabbly.com/incus/stable noble main' | \
  677. sudo tee /etc/apt/sources.list.d/zabbly-incus-stable.list
  678. sudo apt update
  679. sudo apt install incus incus-tools incus-client
  680. incus --version # 6.19 or later
  681. ```
  682. ---
  683. ## API
  684. Containarium exposes:
  685. - **REST API** at `http://localhost:8080` (gRPC-gateway over the gRPC
  686. service, JWT auth)
  687. - **gRPC** at `:50051` (mTLS, primarily used by the CLI)
  688. - **Two MCP servers**: `mcp-server` (platform) and `agent-box`
  689. (in-the-box)
  690. OpenAPI / Swagger UI at
  691. `http://localhost:8080/swagger-ui/`.
  692. Token-issuance is **CLI-only** by design; the daemon does not have an
  693. "issue token via API" endpoint, because if it did, anyone with API
  694. access could mint admin tokens.
  695. ---
  696. ## Hardening notes
  697. ### SSH key hygiene
  698. - Each user gets their own keypair. **Never** share keys between users
  699. — sharing breaks revocation, audit, and per-user fail2ban.
  700. <!-- claim-exempt: key-handling advice, asserts no property of the product -->
  701. - The same key can authenticate to both the sentinel proxy account and
  702. the container. That's the supported flow: simpler for users, no
  703. security loss because the proxy account is `nologin` and only routes
  704. through.
  705. - To rotate: user generates a new key, admin replaces the
  706. `authorized_keys` content in the container.
  707. ### Agent-box sandbox
  708. If you're running an untrusted agent, set `AGENTBOX_ROOT` to a project
  709. directory:
  710. ```bash
  711. # In the container
  712. export AGENTBOX_ROOT=/srv/project
  713. agent-box # all file ops now constrained to /srv/project
  714. ```
  715. `shell_exec` is intentionally not constrained beyond the LXC container
  716. boundary itself — by design, that's the tool's contract. If you need
  717. tighter isolation, run agent-box in a more restrictive container (e.g.
  718. nested LXC, or chroot the user account further).
  719. <!-- claim-exempt: disclaims isolation for shell_exec rather than claiming it -->
  720. ### Network
  721. - Backend VMs have **no public IP** by default; they reach out via
  722. Cloud NAT and accept inbound only via sshpiper.
  723. - Sentinel allowlist: configure `allowed_ssh_sources` in Terraform
  724. (or firewall rules manually) to lock down who can hit port 22.
  725. ---
  726. ## Comparison FAQ
  727. **Why not Docker / Podman?**
  728. Docker is for application containers. Containarium uses LXC system
  729. containers — full Linux OS per container, real `systemd`, native SSH,
  730. Docker-in-LXC works, persistent filesystem. If your agent will
  731. `apt install` and reboot, you want LXC.
  732. **Why not Kubernetes?**
  733. K8s orchestrates application containers across nodes — that's the
  734. infrastructure layer. Containarium is the agent runtime that runs *on
  735. top of* Kubernetes (or LXC), giving each agent a persistent, SSH-native
  736. box without handing it cluster credentials. If you're already on K8s,
  737. run `containariumd daemon --runtime=k8s` and use your existing cluster as
  738. the backend. See the [Kubernetes backend](#kubernetes-backend-experimental)
  739. section and [docs/KIND-QUICKSTART.md](docs/KIND-QUICKSTART.md).
  740. **Why not Vagrant?**
  741. Vagrant orchestrates VMs on a developer's local machine. Containarium
  742. hosts environments on shared remote infrastructure for many agents.
  743. **Why not Dev Containers / VS Code Remote Containers?**
  744. Dev Containers are project-scoped, IDE-coupled, single-developer.
  745. Containarium gives many users (or many of one user's agents) their own
  746. persistent boxes on shared infrastructure, IDE-agnostic.
  747. **Why not Codespaces / Gitpod?**
  748. Browser-IDE-as-a-Service, per-hour billed, vendor-locked. Containarium
  749. is self-hosted, persistent, SSH/MCP-based, no per-hour billing in OSS.
  750. **Why not e2b / Modal / Daytona?**
  751. Closest peers — sandboxes for AI agents. They're SaaS-only and
  752. typically optimize for short-lived, process-per-call execution.
  753. Containarium is self-hostable, MCP-native, and gives you full
  754. persistent Linux boxes. Pick e2b if you want hosted-only and
  755. ephemeral; pick Containarium if you want self-hosted, persistent,
  756. and your data on your infra.
  757. **Why LXC at all?**
  758. - Each container runs a full Linux OS with `systemd`.
  759. - SSH access is first-class.
  760. - Docker-in-LXC works (vs. fragile Docker-in-Docker).
  761. - Real persistent filesystem, real users, real `sudo`.
  762. - "Feels like a VM" for the agent — same surface area as a managed
  763. cloud VM, fraction of the resource cost.
  764. ---
  765. ## Use cases
  766. - **AI-agent sandboxes** (the lead): Cursor, Claude Code, Cline,
  767. OpenCode, custom agents — all reach the same MCP surface.
  768. - **Shared developer environments**: many developers, one host, SSH
  769. jump server with per-user accounts and containers (isolation
  770. caveats: [`docs/security/CLAIMS.md`](docs/security/CLAIMS.md)).
  771. - **ML / GPU experimentation**: GPU passthrough into LXC.
  772. - **Education, bootcamps, workshops**: per-student isolated Linux
  773. with no per-student VM.
  774. - **CI / build infrastructure**: long-lived build hosts that keep
  775. caches warm across runs.
  776. - **Demo / testing infrastructure**: spin up a real Linux env, test,
  777. tear down.
  778. ---
  779. ## In the wild
  780. Where Containarium has been demonstrated live:
  781. - **2026-08 — COSCUP, Taipei.** *An SSH-native agent runtime, built
  782. because our hardware was sitting idle* — where utilisation goes on AI
  783. and VM fleets, why one VM per developer stopped paying for itself, and
  784. how LXC + sshpiper + persistent disk became Containarium.
  785. [Slides](https://containarium.dev/talks/coscup2026).
  786. - **2026-06-04 — AI Agent Night, Taipei.** When the grand-prize
  787. giveaway (a custom vibe-keyboard) hit a snag — the event had no way
  788. to run the lucky draw — we fired up Containarium and vibe-coded a
  789. lucky-draw picker on the spot to save the giveaway. Still live:
  790. [lucky-draw.demo.containarium.dev](https://lucky-draw.demo.containarium.dev/).
  791. Demoed Containarium somewhere? Open a PR and add it here.
  792. ---
  793. ## Status
  794. - **Production-deployed** on GCP (multi-region) and bare-metal GPU
  795. nodes.
  796. - **APIs are stable** (protobuf-defined with gRPC-gateway).
  797. - **Apache 2.0**, no CLA, accepting community PRs.
  798. - Active maintenance: see commit history on `main` and recent
  799. releases.
  800. ---
  801. ## Roadmap
  802. - **Shipped (2026-06)**: **[Kubernetes backend](#kubernetes-backend-experimental)**
  803. <!-- claim-row: Kubernetes boxes get a default-deny NetworkPolicy. -->
  804. — run a box as a pod in a cluster you operate, reached over SSH like an LXC
  805. box, with the sshpiper gateway, default-deny NetworkPolicy, CSI storage, and
  806. `nvidia.com/gpu` passthrough. Selected at runtime via `--runtime=k8s` (no
  807. recompile). End-to-end validated on `kind`; 5-minute local bring-up in
  808. [docs/KIND-QUICKSTART.md](docs/KIND-QUICKSTART.md). See also
  809. [docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md](docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md).
  810. - **Shipped**: `agent-box` MCP, `ssh-config` CLI, `expose-port` CLI, and
  811. the demo recording — the [Quick start](#quick-start) above is built on
  812. them.
  813. - **Q3 2026**: `agent-box` tier-2 (MCP Roots, background process
  814. management), demo-driven docs and examples.
  815. - **Q4 2026**: OSS v1.0 cut — stable API surface, contribution
  816. guide.
  817. If you want to drive an item, open an issue or PR — community work is
  818. welcome and we triage weekly.
  819. ---
  820. ## Contributing
  821. - Read [CLAUDE.md](CLAUDE.md) for the CLI-first principle (every new
  822. platform action lands as `containarium <verb>` first; MCP wraps it).
  823. - Check [existing issues and PRs](https://github.com/footprintai/Containarium/issues).
  824. - Add tests for new features.
  825. - Update docs if user-visible behavior changes.
  826. No CLA. Apache 2.0 means you can use, modify, and redistribute. We
  827. welcome PRs that align with the project's positioning and reject
  828. those that don't (e.g. "let me add multi-tenancy to the OSS daemon"
  829. goes into the cloud repo discussion, not here).
  830. ---
  831. ## License
  832. Apache License 2.0 — see [LICENSE](LICENSE).
  833. ---
  834. ## Acknowledgments
  835. - [Incus](https://linuxcontainers.org/incus/) — modern LXC manager.
  836. - [sshpiper](https://github.com/tg123/sshpiper) — SSH reverse proxy.
  837. - [mcp-go](https://github.com/mark3labs/mcp-go) — Go MCP server library.
  838. - [Caddy](https://caddyserver.com/) — TLS / reverse proxy with
  839. PROXY-protocol support.
  840. - [Cobra](https://cobra.dev/) — CLI framework.
  841. - [Terraform](https://terraform.io/) — infrastructure as code.
  842. ---
  843. ## Support
  844. - **Project site**: [containarium.dev](https://containarium.dev) — overview, hosted cloud, GitHub Action for CI, PR previews.
  845. - **Documentation**: [docs/](docs/) directory.
  846. - **Issues**: [GitHub Issues](https://github.com/footprintai/Containarium/issues).
  847. - **Demo video**: [55s walkthrough on YouTube](https://youtu.be/IBDDD_tb8FY).
  848. - **Live demo app**: [helloworld.demo.containarium.dev](https://helloworld.demo.containarium.dev).
  849. - **Organization**: [FootprintAI](https://github.com/footprintai).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.