containarium

module
v0.130.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0

README

Containarium — Agent Runtime

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

The open-source, self-hostable agent runtime for AI agents. 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.

Bring your own agent — Cursor, Claude Code, OpenCode, your own MCP client. We run the box.

agent: "create me a sandbox called 'blog'"           → containarium create
agent: "wire up SSH so I can reach it"               → containarium ssh-config sync
agent: "install Caddy on :8080 inside the box"       → shell_exec (via agent-box MCP)
agent: "expose that on blog.example.com"             → containarium expose-port

curl https://blog.example.com → hello world

License Go OpenSSF Scorecard Containarium MCP server

Containarium MCP server

Stack Fingerprint

🌐 Project site: containarium.dev · 🎬 55s demo: youtu.be/IBDDD_tb8FY · 🚀 Live app: helloworld.demo.containarium.dev


Choose your path

Path You end up with Go to
Hosted cloud a box you can ssh into with your agent wired to it, no server to run Sign up at cloud.containarium.dev
Self-host on a VM the same, on your own Ubuntu VM (about 5 minutes) Quick start
See the end result a live app served from a box, which is what you end up with helloworld.demo.containarium.dev

Why an agent runtime?

AI agents are increasingly the primary user of dev infrastructure. They want to build, install, deploy, and verify — not on the human's laptop (too noisy, too risky, too local) but on a persistent runtime that's:

  • Persistent: state survives between agent runs.
  • 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.)
  • Real: a full Linux environment with systemd, real networking, and the ability to host things on the open internet.
  • Driven by structured tools: not by an agent typing commands into a TTY hoping nothing scrolls off-screen, but by MCP — typed, bounded, safe.
  • Blast-radius-bounded: the agent holds an SSH key, not a kube-apiserver token. It can't reach the cluster control plane, the host OS, or other tenants' boxes.

That's the runtime Containarium gives you. It runs as a self-hosted platform on LXC or Kubernetes, exposes its admin surface over MCP, and ships a second MCP server that lives inside the box so the agent can shell_exec and edit files directly.

You bring the agent. We run the box.


Quick start

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). 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

quickstart creates the box, reuses your ~/.ssh key or generates a managed one (~/.ssh/containarium_ed25519), writes ~/.containarium/ssh_config, adds the single Include ~/.containarium/ssh_config line to ~/.ssh/config, and wires the box into your agent's MCP config (Claude Code by default). It's safe to run again, including to repair an older quickstart's MCP command.

✅ 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. On a single VM, ssh-config sync adds a ProxyJump through the VM's per-user jump account when the daemon doesn't advertise ssh_host. If the API is reached directly, the jump host defaults to the API hostname, on SSH port 22. With the API tunnel below, name the actual VM with --jump-host (use <vm-host>:<ssh-port> for a custom SSH port). Deployments with a sentinel can use --sentinel <sentinel-host> instead; a daemon's --ssh-host still takes precedence over the jump route.

# 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)"

containarium ssh-config sync --jump-host <vm-host>

Then make Include ~/.containarium/ssh_config the first line of your laptop's ~/.ssh/config. Use the key whose public half was supplied when creating the box: that key is authorized on both the box and its VM jump account. Add --identity ~/.ssh/<your-private-key> to sync if needed; it applies to both SSH connections.

✅ Check:

ssh alice-container hostname   # → alice-container
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

On the machine where your agent runs, quickstart wires the MCP config automatically. Step 1 already did this for Claude Code on the VM. If your agent runs on your laptop, run this there using the API connection from step 2; it reuses the existing box:

containarium quickstart alice --agent claude
# For Gemini or Codex, use --agent gemini or --agent codex instead.

For Cursor, add the server to ~/.cursor/mcp.json manually:

{
  "mcpServers": {
    "containarium-box": {
      "command": "ssh",
      "args": ["alice", "sh -c 'PATH=\"$HOME/.local/bin:/usr/local/bin:$PATH\" exec agent-box'"]
    }
  }
}

This command sets the box's PATH for non-interactive SSH and supports both user-level and system-wide installs of agent-box.

✅ Check: your agent lists containarium-box as a connected MCP server (in Claude Code, claude mcp list). Asking it to "run uname -a in the box" returns a Linux kernel line from alice-container. It now has shell_exec, read_file, write_file, list_directory, move_file and delete_file inside the box.

That's your first box. Next: run the agent on the box · run pi inside the box · put the box on a public hostname · build a site in one command.


After your first box

Run the agent on the box

code install (step 3) already put Claude Code on the box. It installs no credential: sign-in goes through Anthropic's own flow, never through us. Choose one of these, once:

# interactive: sign in inside the box (device code)
ssh alice
claude

# or headless: your own key in the "env" block of ~/.claude/settings.json on the box
#   {"env": {"ANTHROPIC_API_KEY": "<your key>"}}

Then:

containarium code run alice --prompt "add a health endpoint and run the tests"

code run streams output to your terminal as it's produced, but it isn't a pipe. The run is detached on the box and its output is captured to a log; your terminal is a resumable reader over that log. Close your laptop, lose wifi, press Ctrl-C: the run keeps going, and containarium code attach alice picks the stream back up byte-exact, with nothing missing and nothing repeated.

containarium code attach alice   # reconnect; replays what you missed
containarium code status alice   # liveness, and the exit code once it finishes
containarium code stop alice     # reap it; the log stays readable

The difference from the MCP wiring in step 3 is where the agent runs. There, the agent is on your machine and reaches into the box. Here, the agent is on the box, so the work survives your machine sleeping, and the tests run next to the code instead of over a network hop.

Run pi inside the box

If your agent has no MCP client, run it inside the box instead. See docs/integrations/pi.md for the pi walkthrough (installs, keys, code sync, sessions).

Put the box on a public hostname
containarium expose-port alice \
  --container-port 8080 \
  --domain blog.example.com

Caddy on the sentinel terminates TLS for blog.example.com and forwards to alice-container:8080. curl https://blog.example.com then hits whatever alice is serving on port 8080.

Build a site in one command

Run from your laptop against a server you can reach (see step 2, variant B), quickstart does steps 1–3 in one go: it creates the box and wires SSH and your agent (claude, gemini or codex). With --prompt it also exposes --domain and launches your local agent on the build:

containarium quickstart alice --server <your-server> \
  --prompt "a coffee-shop landing page" --domain coffee.example.com

containarium quickstart --help lists every option.


The four primitives

Every action in Containarium has a CLI verb (canonical) AND an MCP tool (thin wrapper that delegates to the same Go function). See CLAUDE.md for the convention.

agent-box — in-the-box MCP server

Runs inside every container. Reached over stdio (typically wrapped by SSH on the client side). Exposes Linux-native operations:

Tool What it does
shell_exec Run a shell command, capture stdout/stderr/exit, bounded by timeout (default 30s, max 10min) and 256 KiB output cap
read_file Byte range OR head=N lines OR tail=N lines
write_file Atomic write with mkdirp (temp + rename)
list_directory Type/size/mtime, hidden filtering
move_file Atomic rename with mkdirp on destination
delete_file Single-file remove (refuses directories so recursive deletes go via shell_exec where blast radius is explicit)

Resources (read-only data the agent fetches via MCP resources/read):

URI What it returns
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.
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.

Optional sandbox: when AGENTBOX_ROOT is set, every file-ops path is resolved against that root with a boundary-aware prefix check. Default unset = no constraint. See internal/agentbox/ for the Go implementation.

mcp-server — platform MCP server

Runs on the host. Exposes the platform's outside-the-box operations as MCP tools — about a hundred of them, one per CLI verb: container lifecycle (create_container, list_containers, start_container, stop_container, delete_container, resize_container), networking (expose_port, sync_ssh_config, passthrough routes), coding-agent runs (code_run, code_attach, code_status, code_stop), secrets, backups, recipes, security scans, tracker connections, and get_metrics / get_system_info. A token's scopes decide which ones a client sees. See cmd/mcp-server/ and internal/mcp/ for the catalog.

containarium CLI

Same surface as the platform MCP, plus deeper administration. The verbs this README uses (the CLI has about ninety — containarium --help lists them all):

containarium quickstart         Create a box, wire SSH + your agent, optionally build a site
containarium create             Create a new container
containarium list               List all containers
containarium wake / sleep       Start a stopped box / stop a running one
containarium delete             Delete a container
containarium code               Run a coding agent ON a box (install / run / attach / logs / runs / status / stop / egress-policy)
containarium expose-port        Expose container:port on a public hostname
containarium ssh-config         Generate self-contained ssh_config (show / sync)
containarium route              Manage proxy routes (low-level)
containarium passthrough-route  Manage TCP/UDP passthrough routes (daemon API)
containarium token              Issue, inspect, refresh and revoke JWT tokens
containarium login / connect    Device-flow sign-in to a server; open a shell on a box with that token
containarium info               Container or system info
containarium version            Print version

Host-side verbs (daemon, sentinel, passthrough, audit, doctor, …) live in containariumd — see Two binaries. Run containarium <verb> --help for full options.

Sentinel — sshpiper + Caddy + PROXY-protocol

The sentinel is a tiny always-on VM (e2-micro on GCP free tier works) that:

  • Receives SSH on port 22 (sshpiper routes to the right backend by username).
  • Receives HTTPS on 443 (Caddy with TLS-passthrough or PROXY-protocol-aware forwarding to backend Caddy).
  • Survives spot-VM termination on the backend with a maintenance page.
  • Holds the static IP / DNS A-record so backends can be ephemeral.

See docs/SENTINEL-DESIGN.md for the full design.


Architecture

        Agent (Cursor / Claude Code / OpenCode)
            │
            │ JWT (access; tt=access, jti, scopes)
            │ MCP over stdio  ──┐
            │                   │ ┌── refresh ──> POST /v1/tokens/refresh
            v                   ▼ │                  (single-use; old jti revoked)
        ssh user@box  → sshpiper → agent-box (in container)
            │
            │ HTTPS  (mTLS upstream; PROXY-protocol v2)
            v
        Sentinel (e2-micro, always-on)
        ├── sshpiper (port 22)            : routes by username; fail2ban per-user
        ├── Caddy + PROXY-protocol (443)  : routes by hostname / SNI suffix
        └── /wake/ source-IP allowlist    : trusted-proxy only
            │
            v
        +-------------------------------------------------+
        | Backend VM (spot or bare-metal GPU node)        |
        |                                                 |
        |  Incus (LXC) ── containers                      |
        |    ├── alice-container    : SSH + agent-box     |
        |    │   └── /run/secrets/* : tmpfs, 0440 alice   |
        |    └── bob-container      : ZFS-backed storage  |
        |                                                 |
        |  Containarium daemon                            |
        |    ├── JWT auth (iss/aud/jti/scopes)            |
        |    ├── Admin RBAC + container-owner authz       |
        |    ├── Image-digest gate (REQUIRE + VERIFY)     |
        |    ├── Secrets ── Postgres (envelope-encrypted) |
        |    │              │                             |
        |    │              v                             |
        |    │           KMS ── Vault Transit / GCP KMS   |
        |    │           (master key retirable post-cutover)
        |    └── Audit log ── Postgres + SHA-256 hash     |
        |                     chain (verify CLI)          |
        +-------------------------------------------------+

A single sentinel can front multiple backend VMs — a "pool" — and a single deployment can run multiple pools (each with its own backends). See docs/MULTI-POOL.md.

Security control surface (all opt-in via env, default-off for upgrade safety; see docs/security/OPERATOR-SECURITY-RUNBOOK.md):

Env var Layer Effect
CONTAINARIUM_REQUIRE_IMAGE_DIGEST=true API refuse images without @sha256:<64hex>
CONTAINARIUM_VERIFY_IMAGE_DIGEST=true API verify digest against the registry index (pre- + post-pull)
CONTAINARIUM_ALLOWED_IMAGE_REGISTRIES API restrict which simplestreams remotes the daemon will pull from
CONTAINARIUM_KMS_BACKEND={none,inproc,vault,gcp} Secrets envelope-encrypt DEKs through an external KMS
CONTAINARIUM_REQUIRE_ENVELOPE=true Secrets refuse legacy master-key-only rows (Phase E retirement gate)
CONTAINARIUM_POSTGRES_URL_FILE / _PASSWORD_FILE Secrets DB creds from disk rather than env
CONTAINARIUM_WAKE_TRUSTED_PROXIES Sentinel source-IP allowlist for /wake/
OTEL_BEARER_REQUIRED=true Telemetry (collector-side; set on the OTel collector, not the daemon) collector rejects un-bearered OTLP submissions

How it's different

vs. SaaS-only sandboxes (e2b, Modal, Replit)

These give you sandboxes for AI agents, but only as hosted SaaS:

  • Self-hostability: Containarium runs on your own infrastructure (a $5 VM, your homelab, your enterprise data center). e2b, Modal, and Replit are SaaS-only — your code, your data, and your customers go through their compute.
  • License: Apache 2.0, no CLA. Fork it, sell it, run it.
  • Surface: full Linux containers with systemd, real network namespaces, GPU passthrough. Not a process-per-call sandbox.
  • Transport: MCP-native from day one, not a custom SDK with MCP bolted on.
vs. Docker AI Sandboxes (sbx)

Docker's sbx run claude and Containarium both call themselves "AI sandboxes," but they sit on opposite ends of the same spectrum:

  • Locality: sbx runs the sandbox on the developer's laptop (microVM, host-isolation). Containarium runs the sandbox on a VM you host (LXC, multi-tenant, public-internet reachable via the sentinel).
  • Persistence: sbx is session-shaped (workspace mount, no documented "give me a box that survives reboot and has a hostname"). Containarium containers persist indefinitely, with ZFS snapshots and 30-day retention.
  • Public reach: containarium expose-port alice --domain blog.example.com is one verb. sbx is laptop-local; no public-hostname story.
  • Agent surface: sbx is CLI-first (sbx run <agent>). Containarium is MCP-native — two MCP servers (in-the-box agent-box + platform mcp-server) plus the same surface via CLI, SSH, REST/gRPC, and a web UI.
  • License: sbx CLI is free; team policy (Docker Admin Console) is a paid subscription. Containarium is Apache 2.0 — including the audit log, RBAC, KMS integrations, and everything else on this page.

If you're stopping an agent from rm -rf-ing the laptop it's running on, sbx is the lighter tool. If you're giving your agent (or your customer's agent) a persistent Linux box on the public internet, Containarium is the shape.

vs. OSS Kubernetes agent runtimes (agent-sandbox, OpenShell)

kubernetes-sigs/agent-sandbox and NVIDIA/OpenShell are the closest open-source peers on Kubernetes:

  • SSH-native vs. exec-based: both agent-sandbox and OpenShell reach the sandbox via kubectl exec or a proprietary client, which requires the agent to hold a kube-apiserver token or cluster credentials. Containarium reaches the pod over SSH through sshpiper — the agent has no path to the cluster control plane at all.
  • MCP-native: agent-sandbox and OpenShell expose REST APIs or custom SDKs. Containarium's agent-box MCP server runs inside the box, reachable over SSH stdio — any MCP-speaking agent (Claude Code, Cursor, OpenCode) works with zero client library.
  • LXC + K8s, one CLI: Containarium runs on either Incus/LXC or Kubernetes behind the same containarium CLI and --runtime flag. You switch backends without changing anything for the agent.
  • eBPF egress policy: Containarium can enforce per-tenant egress allowlists at the kernel level via TC_INGRESS eBPF programs once an operator arms them (opt-in; see docs/security/CLAIMS.md). agent-sandbox has NetworkPolicy; OpenShell has eBPF but is NVIDIA-stack-specific. Neither offers a portable, per-tenant eBPF allowlist across LXC and K8s backends.
vs. dev environment platforms (Codespaces, Gitpod, Coder)

Those are persistent IDEs. Containarium is a persistent box — agent-driven, not developer-driven, no IDE assumption, SSH-as-the-API:

  • Containarium environments are reached by SSH and MCP. Any IDE works (Vim, JetBrains Remote, VS Code Remote, Cursor's remote dev — your call).
  • Cost: no per-hour billing in the OSS path. Self-host costs are just your underlying VM.
  • Persistence: containers survive indefinitely; Codespaces auto-delete after inactivity.
vs. application container platforms (Docker, Kubernetes)

LXC is a system container, not an application container. Each container has systemd, a real init, real users, real package managers, real sudo. You can run Docker inside a Containarium container; the reverse isn't really a thing.

If your agent is going to apt install half a Linux distro, edit config files in /etc, run a database, and reboot — LXC is the right shape. If your agent runs a single Python process, Docker or Modal is fine.

It isn't either/or: Containarium can run a box as a pod in a Kubernetes cluster you already operate — same SSH-native agent contract, no kube-apiserver token in the agent's hands. Switch with --runtime=k8s. See the Kubernetes backend section below.


What's in the box

Beyond the agent-native primitives, Containarium ships:

Multi-OS
  • Ubuntu 24.04 LTS (default)
  • Rocky Linux 9 (dev/test)
  • RHEL 9 (production)
  • Windows Server VMs via QEMU/KVM with RDP — see docs/WINDOWS-VM-SETUP.md
GPU passthrough

For ML/AI agent workflows. Works with NVIDIA RTX 3090, RTX 4090, and similar. PCI-level passthrough so the container sees the GPU directly. Tested on bare-metal GPU nodes connected to the sentinel via tunnel.

Multi-backend

A single sentinel can front:

  • GCP spot VMs: cost-effective cloud backends with auto-recovery on preemption.
  • Bare-metal GPU nodes: any Linux box you can SSH to; reaches the sentinel via outbound tunnel.
  • Windows VMs: live alongside Linux backends.

All containers from all backends appear in a single unified API.

Kubernetes backend (experimental)

Beyond the LXC/Incus backend, Containarium can run a box as a pod in a Kubernetes cluster you already operate — reached over SSH exactly like an LXC box, so an agent can't tell which substrate it landed on. The daemon reconciles a per-tenant namespace + StatefulSet + headless Service

  • default-deny NetworkPolicy, and programs the sshpiper gateway (the Pipe CRD) so ssh <tenant>@<gateway> routes to the right pod. What the NetworkPolicy does and does not guarantee is in docs/security/CLAIMS.md.

The pitch isn't "another way to run pods" — it's giving an agent a hardened, SSH-native foothold in your cluster without handing it a kube-apiserver token: the box runs with automountServiceAccountToken: false and satisfies the restricted Pod Security profile. Compare this to kubectl exec-based runtimes where the agent necessarily holds cluster credentials.

Runtime selection (no recompile needed):

# LXC/Incus (default)
containariumd daemon

# Kubernetes — uses in-cluster config or KUBECONFIG
CONTAINARIUM_RUNTIME=k8s containariumd daemon
# or
containariumd daemon --runtime=k8s

Both backends share the same CLI, MCP tools, JWT auth, and REST/gRPC API. GPU passthrough is supported on K8s via nvidia.com/gpu resource limits. Local bring-up takes under 5 minutes with kind — see docs/KIND-QUICKSTART.md.

Design, topology, and BYO-cluster integration: docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md.

Web UI

A basic dashboard at /webui/ for users who'd rather not type CLI: container list, lifecycle controls, metrics, browser-based terminal. Polished UI is intentionally a cloud-product concern — the OSS web UI is functional, not opinionated.

Persistent storage (ZFS)

Containers survive VM restarts and spot termination. ZFS handles compression, snapshots (daily by default, 30-day retention), and checksums.

Sentinel HA

The sentinel itself is e2-micro (free tier). It:

  • Detects spot preemption in ~10s, serves a maintenance page.
  • Restarts spot VMs automatically (~85s total recovery).
  • Holds the static IP, so DNS doesn't change as backends rotate.
Monitoring & observability

VictoriaMetrics + Grafana auto-provisioned. Per-container CPU, memory, disk, network. Alerting via webhooks. SSH audit logs per user (LXC backend; the Kubernetes backend records control-plane API audit but not in-box SSH sessions — see #1189).

Security primitives
  • Unprivileged LXC containers: container root ≠ host root.
  • Per-user proxy accounts: /usr/sbin/nologin on the sentinel, users can only proxy through to their container.
  • fail2ban per-user: an attack on Alice's account doesn't ban Bob.
  • 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.
  • AppArmor profiles per container.
  • AGENTBOX_ROOT sandbox to constrain agent-box file ops at runtime.

Zero-trust controls (see docs/security/OPERATOR-SECURITY-RUNBOOK.md; several are opt-in, see docs/security/CLAIMS.md for what is on by default):

  • JWT with iss / aud / jti / tt / scopes: 32-byte minimum secret enforced at startup; refresh tokens are single-use; jti-based revocation; per-tool MCP scopes propagate to server-side gates.
  • Admin RBAC + per-container ownership on the API surface; cluster ops admin-only, container ops owner-only.
  • KMS envelope encryption for tenant secrets (Vault Transit or GCP Cloud KMS), with a migration tool and master-key retirement gate.
  • tmpfs --delivery=file for secrets that shouldn't be visible in /proc/<pid>/environ.
  • Audit log with SHA-256 hash chain + containariumd audit verify (on the host): tamper-evident against an application- or database-level attacker. An attacker who can write the database can rewrite the chain consistently; the chain root can be anchored to a file outside the database (internal/audit/anchor.go), which a database credential does not reach, but a host-root attacker could still edit both.
  • Image-registry allowlist + pre-pull simplestreams digest verification + post-pull volatile.base_image defense-in-depth for supply-chain hardening.
  • SECURITY.md with a 90-day coordinated-disclosure window; gosec / govulncheck / trivy running in CI.

CLI reference (essentials)

Container lifecycle
# Create (Ubuntu 24.04, default)
containarium create alice --ssh-key ~/.ssh/id_ed25519.pub

# Create with options
containarium create ml-dev \
  --ssh-key ~/.ssh/id_ed25519.pub \
  --gpu 0 \
  --stack gpu \
  --memory 16GB \
  --cpu 4

# Lifecycle
containarium list
containarium info
containarium wake alice     # start a stopped box
containarium sleep alice    # stop it
containarium delete alice
Networking
# Expose a container port on a public hostname
containarium expose-port alice \
  --container-port 8080 \
  --domain blog.example.com

# Lower-level route management
containarium route add api.example.com --target 10.0.3.42:3000
containarium route list
containarium route delete api.example.com

# Raw TCP/UDP passthrough via local iptables (on the host, so it's a
# containariumd verb)
containariumd passthrough add --port 50051 \
  --target-ip 10.0.3.150 --target-port 50051

# Raw TCP/UDP passthrough via the daemon API (works against a remote box)
containarium passthrough-route add --port 9443 \
  --target-ip 10.0.3.150 --target-port 50051 --server <host:port>
containarium passthrough-route list --server <host:port>
containarium passthrough-route remove --port 9443 --server <host:port>
SSH config
# Print to stdout (preview)
containarium ssh-config show

# Write to ~/.containarium/ssh_config (one-line `Include` to wire in)
containarium ssh-config sync
containarium ssh-config sync --sentinel sentinel.example.com  # via sentinel
containarium ssh-config sync --identity ~/.ssh/containarium_ed25519

# From a client machine, against a remote server (the bare form above
# only reaches a local Incus socket)
containarium ssh-config sync --http --server <host:port>
Authentication
# Issue an access + refresh pair (CLI-only; never exposed via API).
# Access tokens are short-lived (default 15 min) and authenticate the
# API. Refresh tokens are long-lived and single-use — exchange via
# POST /v1/tokens/refresh for a new pair.
containarium token generate \
  --username admin \
  --roles admin \
  --secret-file /etc/containarium/jwt.secret

# Use the access token
curl -H "Authorization: Bearer <access-token>" http://localhost:8080/v1/containers

# Exchange the refresh token for a new pair (same as POST /v1/tokens/refresh;
# the refresh token is the credential, so no --token)
containarium token refresh --refresh-token "$REFRESH" --server <host:port>

# Inspect a token's claims (jti, scopes, expiry, validation)
containarium token inspect <token> --secret-file /etc/containarium/jwt.secret

# Revoke a leaked token by jti (idempotent; reads from `audit query`
# or `token inspect`)
containarium token revoke <jti> --reason "leak_2026_05_22"
containarium token list-revoked

# Mint a least-privilege token for an agent with only the scopes it
# needs — server-side gates enforce this even if the agent ignores
# the filter.
containarium token generate \
  --username alice-agent \
  --scopes containers:read,containers:write \
  --secret-file /etc/containarium/jwt.secret

See docs/security/OPERATOR-SECURITY-RUNBOOK.md for the full token lifecycle, leak-response playbook, and the agent least-privilege scope catalog.


Deployment

Two binaries: containarium vs containariumd

Same convention as docker/dockerd or incus/incusd: containarium is the CLI you run from your laptop (create, list, ssh-config, expose-port, …); containariumd is what runs on the host — the daemon, the sentinel, and every on-host admin verb (daemon, sentinel, service install, sync-accounts, pool join, node, hosting, recover, doctor). Install containarium wherever you want to drive the platform from (your laptop, a jump box); install containariumd on every host that runs the daemon or sentinel itself. A compat symlink (/usr/local/bin/containarium -> containariumd) keeps existing hosts and scripts that still invoke containarium <daemon verb> working during the rollout.

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

See hacks/README.md for what the script does.

cd terraform/gce
cp examples/single-server-spot.tfvars terraform.tfvars
vim terraform.tfvars   # set project_id, admin_ssh_keys, allowed_ssh_sources
terraform init
terraform apply

See terraform/gce/README.md for variables.

System requirements
  • Host OS: Ubuntu 24.04 LTS or later, or Debian 13 (trixie) (containers can be any supported OS). Debian 13 has been verified with the installer; Debian 12 is accepted but untested. The ZFS kernel module is optional on Debian, where the cloud kernel does not ship it; disk quotas then need another storage backend.
  • Incus 6.19+ required for Docker-in-LXC support. Ubuntu 24.04's default repos ship 6.0.0 which has an AppArmor bug (CVE-2025-52881); use the Zabbly Incus repository for current builds.
  • ZFS kernel module (for disk quotas).
  • Kernel modules: overlay, br_netfilter, nf_nat (Docker in containers needs these).
# Quick Incus install via Zabbly
curl -fsSL https://pkgs.zabbly.com/key.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/zabbly-incus.gpg
echo 'deb [signed-by=/usr/share/keyrings/zabbly-incus.gpg] \
  https://pkgs.zabbly.com/incus/stable noble main' | \
  sudo tee /etc/apt/sources.list.d/zabbly-incus-stable.list
sudo apt update
sudo apt install incus incus-tools incus-client
incus --version  # 6.19 or later

API

Containarium exposes:

  • REST API at http://localhost:8080 (gRPC-gateway over the gRPC service, JWT auth)
  • gRPC at :50051 (mTLS, primarily used by the CLI)
  • Two MCP servers: mcp-server (platform) and agent-box (in-the-box)

OpenAPI / Swagger UI at http://localhost:8080/swagger-ui/.

Token-issuance is CLI-only by design; the daemon does not have an "issue token via API" endpoint, because if it did, anyone with API access could mint admin tokens.


Hardening notes

SSH key hygiene
  • Each user gets their own keypair. Never share keys between users — sharing breaks revocation, audit, and per-user fail2ban.
  • The same key can authenticate to both the sentinel proxy account and the container. That's the supported flow: simpler for users, no security loss because the proxy account is nologin and only routes through.
  • To rotate: user generates a new key, admin replaces the authorized_keys content in the container.
Agent-box sandbox

If you're running an untrusted agent, set AGENTBOX_ROOT to a project directory:

# In the container
export AGENTBOX_ROOT=/srv/project
agent-box   # all file ops now constrained to /srv/project

shell_exec is intentionally not constrained beyond the LXC container boundary itself — by design, that's the tool's contract. If you need tighter isolation, run agent-box in a more restrictive container (e.g. nested LXC, or chroot the user account further).

Network
  • Backend VMs have no public IP by default; they reach out via Cloud NAT and accept inbound only via sshpiper.
  • Sentinel allowlist: configure allowed_ssh_sources in Terraform (or firewall rules manually) to lock down who can hit port 22.

Comparison FAQ

Why not Docker / Podman? Docker is for application containers. Containarium uses LXC system containers — full Linux OS per container, real systemd, native SSH, Docker-in-LXC works, persistent filesystem. If your agent will apt install and reboot, you want LXC.

Why not Kubernetes? K8s orchestrates application containers across nodes — that's the infrastructure layer. Containarium is the agent runtime that runs on top of Kubernetes (or LXC), giving each agent a persistent, SSH-native box without handing it cluster credentials. If you're already on K8s, run containariumd daemon --runtime=k8s and use your existing cluster as the backend. See the Kubernetes backend section and docs/KIND-QUICKSTART.md.

Why not Vagrant? Vagrant orchestrates VMs on a developer's local machine. Containarium hosts environments on shared remote infrastructure for many agents.

Why not Dev Containers / VS Code Remote Containers? Dev Containers are project-scoped, IDE-coupled, single-developer. Containarium gives many users (or many of one user's agents) their own persistent boxes on shared infrastructure, IDE-agnostic.

Why not Codespaces / Gitpod? Browser-IDE-as-a-Service, per-hour billed, vendor-locked. Containarium is self-hosted, persistent, SSH/MCP-based, no per-hour billing in OSS.

Why not e2b / Modal / Daytona? Closest peers — sandboxes for AI agents. They're SaaS-only and typically optimize for short-lived, process-per-call execution. Containarium is self-hostable, MCP-native, and gives you full persistent Linux boxes. Pick e2b if you want hosted-only and ephemeral; pick Containarium if you want self-hosted, persistent, and your data on your infra.

Why LXC at all?

  • Each container runs a full Linux OS with systemd.
  • SSH access is first-class.
  • Docker-in-LXC works (vs. fragile Docker-in-Docker).
  • Real persistent filesystem, real users, real sudo.
  • "Feels like a VM" for the agent — same surface area as a managed cloud VM, fraction of the resource cost.

Use cases

  • AI-agent sandboxes (the lead): Cursor, Claude Code, Cline, OpenCode, custom agents — all reach the same MCP surface.
  • Shared developer environments: many developers, one host, SSH jump server with per-user accounts and containers (isolation caveats: docs/security/CLAIMS.md).
  • ML / GPU experimentation: GPU passthrough into LXC.
  • Education, bootcamps, workshops: per-student isolated Linux with no per-student VM.
  • CI / build infrastructure: long-lived build hosts that keep caches warm across runs.
  • Demo / testing infrastructure: spin up a real Linux env, test, tear down.

In the wild

Where Containarium has been demonstrated live:

  • 2026-08 — COSCUP, Taipei. An SSH-native agent runtime, built because our hardware was sitting idle — where utilisation goes on AI and VM fleets, why one VM per developer stopped paying for itself, and how LXC + sshpiper + persistent disk became Containarium. Slides.
  • 2026-06-04 — AI Agent Night, Taipei. When the grand-prize giveaway (a custom vibe-keyboard) hit a snag — the event had no way to run the lucky draw — we fired up Containarium and vibe-coded a lucky-draw picker on the spot to save the giveaway. Still live: lucky-draw.demo.containarium.dev.

Demoed Containarium somewhere? Open a PR and add it here.


Status

  • Production-deployed on GCP (multi-region) and bare-metal GPU nodes.
  • APIs are stable (protobuf-defined with gRPC-gateway).
  • Apache 2.0, no CLA, accepting community PRs.
  • Active maintenance: see commit history on main and recent releases.

Roadmap

  • Shipped (2026-06): Kubernetes backend — run a box as a pod in a cluster you operate, reached over SSH like an LXC box, with the sshpiper gateway, default-deny NetworkPolicy, CSI storage, and nvidia.com/gpu passthrough. Selected at runtime via --runtime=k8s (no recompile). End-to-end validated on kind; 5-minute local bring-up in docs/KIND-QUICKSTART.md. See also docs/K8S-AGENT-BOX-RUNTIME-DESIGN.md.
  • Shipped: agent-box MCP, ssh-config CLI, expose-port CLI, and the demo recording — the Quick start above is built on them.
  • Q3 2026: agent-box tier-2 (MCP Roots, background process management), demo-driven docs and examples.
  • Q4 2026: OSS v1.0 cut — stable API surface, contribution guide.

If you want to drive an item, open an issue or PR — community work is welcome and we triage weekly.


Contributing

  • Read CLAUDE.md for the CLI-first principle (every new platform action lands as containarium <verb> first; MCP wraps it).
  • Check existing issues and PRs.
  • Add tests for new features.
  • Update docs if user-visible behavior changes.

No CLA. Apache 2.0 means you can use, modify, and redistribute. We welcome PRs that align with the project's positioning and reject those that don't (e.g. "let me add multi-tenancy to the OSS daemon" goes into the cloud repo discussion, not here).


License

Apache License 2.0 — see LICENSE.


Acknowledgments

  • Incus — modern LXC manager.
  • sshpiper — SSH reverse proxy.
  • mcp-go — Go MCP server library.
  • Caddy — TLS / reverse proxy with PROXY-protocol support.
  • Cobra — CLI framework.
  • Terraform — infrastructure as code.

Support

Directories

Path Synopsis
apis
containarium/v1alpha1
Package v1alpha1 contains the API types for the containarium.dev group — the Box CRD the daemon reconciles into a per-tenant agent-box (Sandbox + Pipe + Secret + NetworkPolicy).
Package v1alpha1 contains the API types for the containarium.dev group — the Box CRD the daemon reconciles into a per-tenant agent-box (Sandbox + Pipe + Secret + NetworkPolicy).
cmd
agent-box command
agent-box is the in-the-box MCP server.
agent-box is the in-the-box MCP server.
containariumd command
deps-guard command
Command deps-guard is the CI half of the dependency-change gate (#2794).
Command deps-guard is the CI half of the dependency-change gate (#2794).
ebpf-phase0 command
Command ebpf-phase0 is the Go-side validator for the eBPF network isolation design's Phase 0.
Command ebpf-phase0 is the Go-side validator for the eBPF network isolation design's Phase 0.
ebpf-phaseA command
Command ebpf-phaseA is the on-backend validator for Phase A of the eBPF network-isolation design (docs/security/NETWORK-ISOLATION-DESIGN.md, #315).
Command ebpf-phaseA is the on-backend validator for Phase A of the eBPF network-isolation design (docs/security/NETWORK-ISOLATION-DESIGN.md, #315).
mcp-server command
model-gateway command
Command model-gateway is the agent model gateway (docs/AGENT-MODEL-GATEWAY-DESIGN.md): a credential proxy that can run standalone, without the LXC daemon.
Command model-gateway is the agent model gateway (docs/AGENT-MODEL-GATEWAY-DESIGN.md): a credential proxy that can run standalone, without the LXC daemon.
netpolicy-smoke command
Command netpolicy-smoke is a throwaway end-to-end smoke test for the eBPF network-policy *enforcer* (#315 Phase A piece 6c).
Command netpolicy-smoke is a throwaway end-to-end smoke test for the eBPF network-policy *enforcer* (#315 Phase A piece 6c).
distros
go/containariumotel
Package containariumotel is the Go telemetry distro for apps and services running on the Containarium platform.
Package containariumotel is the Go telemetry distro for apps and services running on the Containarium platform.
go/containariumotel/grpc
Package grpc provides Containarium-flavored gRPC instrumentation.
Package grpc provides Containarium-flavored gRPC instrumentation.
examples
helloworld-go command
helloworld-go: tiny HTTP server demonstrating containariumotel.
helloworld-go: tiny HTTP server demonstrating containariumotel.
images
slides-agent/wsauth command
Command slides-wsauth is the slides-agent image's in-box login helper (#3486).
Command slides-wsauth is the slides-agent image's in-box login helper (#3486).
internal
agentbox
Package agentbox is the in-the-box MCP server library — the tools agents use when working on a single Containarium box.
Package agentbox is the in-the-box MCP server library — the tools agents use when working on a single Containarium box.
agentengine
Package agentengine resolves which agent engine (and which gateway provider) one skill run uses, given the manifest's own choice and the daemon's gateway state.
Package agentengine resolves which agent engine (and which gateway provider) one skill run uses, given the manifest's own choice and the daemon's gateway state.
anonbox
Package anonbox is the daemon side of the `ssh new.<cloud-domain>` door (docs/architecture/ssh-new-anonymous-box.md, #2197): it owns the SSH-key-fingerprint → VM mapping for anonymous boxes.
Package anonbox is the daemon side of the `ssh new.<cloud-domain>` door (docs/architecture/ssh-new-anonymous-box.md, #2197): it owns the SSH-key-fingerprint → VM mapping for anonymous boxes.
app
autosleep
Package autosleep ticks once a minute and stops user containers whose network activity has gone quiet for longer than their per-container idle threshold.
Package autosleep ticks once a minute and stops user containers whose network activity has gone quiet for longer than their per-container idle threshold.
backupkey
Package backupkey holds the operator-side steps of a managed-key restore or verify (#2403), shared by `containarium backup restore|verify` and the MCP restore_backup / verify_backup tools so both run the same code: picking the newest record, and unwrapping a record's per-backup age identity under the caller's own KMS credentials.
Package backupkey holds the operator-side steps of a managed-key restore or verify (#2403), shared by `containarium backup restore|verify` and the MCP restore_backup / verify_backup tools so both run the same code: picking the newest record, and unwrapping a record's per-backup age identity under the caller's own KMS credentials.
capabilities
Package capabilities turns a backend's host system info, GPU passthrough probe, and a bounded CPU/memory micro-benchmark into an explicit capability profile recorded at join.
Package capabilities turns a backend's host system info, GPU passthrough probe, and a bounded CPU/memory micro-benchmark into an explicit capability profile recorded at join.
capacity
Package capacity turns a backend's implicit spare resources into an explicit, policy-bounded scheduling-headroom signal that the control plane can read through the backend surface (ListBackends).
Package capacity turns a backend's implicit spare resources into an explicit, policy-bounded scheduling-headroom signal that the control plane can read through the backend surface (ListBackends).
cloud
Package cloud is the OSS daemon's cloud-actuation client (#354 / docs/CLOUD-ACTUATION-CLIENT-DESIGN.md): the opt-in mode where a registered host receives desired-state container assignments + per-org network policies from a cloud control plane and reconciles them locally.
Package cloud is the OSS daemon's cloud-actuation client (#354 / docs/CLOUD-ACTUATION-CLIENT-DESIGN.md): the opt-in mode where a registered host receives desired-state container assignments + per-org network policies from a cloud control plane and reconciles them locally.
cluster
Package cluster holds the record types, validation, and persistence for managed Kubernetes clusters (#1413) — a platform-operated k3s control plane plus worker VMs in typed size classes.
Package cluster holds the record types, validation, and persistence for managed Kubernetes clusters (#1413) — a platform-operated k3s control plane plus worker VMs in typed size classes.
cmd
Security CLI subcommands — scan, findings, remediate.
Security CLI subcommands — scan, findings, remediate.
codeegress
Package codeegress holds the pure half of the coding tool's egress allowlist (#2370, docs/architecture/coding-cli-egress-allowlist.md): validating a CodingToolEgressPolicy and resolving the effective policy a run takes.
Package codeegress holds the pure half of the coding tool's egress allowlist (#2370, docs/architecture/coding-cli-egress-allowlist.md): validating a CodingToolEgressPolicy and resolving the effective policy a run takes.
coderun
Package coderun implements the client half of `containarium code` (#1674): a resumable reader over agent-box's tail_log, so a run started on a box survives the local client's connection dying mid-stream.
Package coderun implements the client half of `containarium code` (#1674): a resumable reader over agent-box's tail_log, so a run started on a box survives the local client's connection dying mid-stream.
coderun/engine
Package engine makes the coding agent and its credential source typed choices in `containarium code` (#1727), instead of the Claude-only, tenant-secret-only path #1673/#1674 shipped.
Package engine makes the coding agent and its credential source typed choices in `containarium code` (#1727), instead of the Claude-only, tenant-secret-only path #1673/#1674 shipped.
config
Package config centralizes Containarium's environment-driven configuration.
Package config centralizes Containarium's environment-driven configuration.
connectcore
Package connectcore holds the transport-agnostic core of the `containarium connect` flow — the container DTO, SSH-target resolution, and ssh-argv assembly — shared by the CLI verb (internal/cmd/connect.go) and the MCP `connect` tool (internal/mcp/connect.go).
Package connectcore holds the transport-agnostic core of the `containarium connect` flow — the container DTO, SSH-target resolution, and ssh-argv assembly — shared by the CLI verb (internal/cmd/connect.go) and the MCP `connect` tool (internal/mcp/connect.go).
controller
Package controller holds the Box CRD reconciler — the operator half of the Kubernetes agent-box control plane (#995).
Package controller holds the Box CRD reconciler — the operator half of the Kubernetes agent-box control plane (#995).
coreguard
Package coreguard computes the network ACLs that isolate the platform's core-role containers (core-postgres, core-victoriametrics, ...) from tenant containers sharing the same Incus bridge.
Package coreguard computes the network ACLs that isolate the platform's core-role containers (core-postgres, core-victoriametrics, ...) from tenant containers sharing the same Incus bridge.
credentials
Package credentials manages the on-disk store of per-server CLI auth tokens at ~/.containarium/credentials.json, populated by `containarium login` and consumed by the rest of the CLI when no explicit --token / CONTAINARIUM_TOKEN is set.
Package credentials manages the on-disk store of per-server CLI auth tokens at ~/.containarium/credentials.json, populated by `containarium login` and consumed by the rest of the CLI when no explicit --token / CONTAINARIUM_TOKEN is set.
depsguard
Package depsguard is the Go half of the dependency-change gate (#2794, story 3 of #2649).
Package depsguard is the Go half of the dependency-change gate (#2794, story 3 of #2649).
egressproxy
Package egressproxy implements the host-side relay for "egress via client" (#808, Phase 2a).
Package egressproxy implements the host-side relay for "egress via client" (#808, Phase 2a).
gatewayprovider
Package gatewayprovider maps the GatewayProvider proto enum to and from the provider names the model gateway's registry is keyed by.
Package gatewayprovider maps the GatewayProvider proto enum to and from the provider names the model gateway's registry is keyed by.
grpcrecover
Package grpcrecover turns a panic in a gRPC handler into an Internal error.
Package grpcrecover turns a panic in a gRPC handler into an Internal error.
guardrail
Package guardrail drives a detection engine over a set of text units, redacts what it flagged, re-scans the result as the gate, and signs an attestation a consumer can verify before it touches the data (docs/architecture/guardrail.md).
Package guardrail drives a detection engine over a set of text units, redacts what it flagged, re-scans the result as the gate, and signs an attestation a consumer can verify before it touches the data (docs/architecture/guardrail.md).
guardrailpolicy
Package guardrailpolicy stores the cluster-wide, admin-owned guardrail policy (#2368; docs/architecture/guardrail-inbound-and-server-policy.md, "Policy service").
Package guardrailpolicy stores the cluster-wide, admin-owned guardrail policy (#2368; docs/architecture/guardrail-inbound-and-server-policy.md, "Policy service").
guardrailpolicy/pgstore
Package pgstore is the Postgres guardrailpolicy.Store.
Package pgstore is the Postgres guardrailpolicy.Store.
guardrailpolicy/storetest
Package storetest is the behavioural contract every guardrailpolicy.Store must meet.
Package storetest is the behavioural contract every guardrailpolicy.Store must meet.
guardrailrate
Package guardrailrate is the per-subject token-bucket rate limit on the guardrail APIs (#2404): the gated DeployRecipe path and GuardrailPolicyService Set/Get.
Package guardrailrate is the per-subject token-bucket rate limit on the guardrail APIs (#2404): the gated DeployRecipe path and GuardrailPolicyService Set/Get.
guardrailstage
Package guardrailstage is the daemon-side staging area a gated recipe deploy reads its dataset from (#2368; docs/architecture/guardrail-inbound-and-server-policy.md, "The gate").
Package guardrailstage is the daemon-side staging area a gated recipe deploy reads its dataset from (#2368; docs/architecture/guardrail-inbound-and-server-policy.md, "The gate").
hostcheck
Package hostcheck is the host capability self-check from the daemon deploy contract (prd/oss/daemon-deploy-contract.md) — the checks behind the "capability trap": running uid/caps, writability of the daemon's paths, and a live useradd/userdel probe.
Package hostcheck is the host capability self-check from the daemon deploy contract (prd/oss/daemon-deploy-contract.md) — the checks behind the "capability trap": running uid/caps, writability of the daemon's paths, and a live useradd/userdel probe.
hostharden
Package hostharden applies narrow, single-purpose host mitigations that don't require the daemon's full eBPF network-policy engine.
Package hostharden applies narrow, single-purpose host mitigations that don't require the daemon's full eBPF network-policy engine.
hosting
Package hosting provides DNS and SSL setup automation for app hosting.
Package hosting provides DNS and SSL setup automation for app hosting.
hosting/godaddy
Package godaddy provides a client for the GoDaddy API to manage DNS records.
Package godaddy provides a client for the GoDaddy API to manage DNS records.
hostport
Package hostport provides a single, permissive "host:port" splitter.
Package hostport provides a single, permissive "host:port" splitter.
httpx
Package httpx holds small net/http helpers shared by the daemon's HTTP middleware so the next interface gap (Flusher, Hijacker, ReaderFrom, ...) is fixed in one place.
Package httpx holds small net/http helpers shared by the daemon's HTTP middleware so the next interface gap (Flusher, Hijacker, ReaderFrom, ...) is fixed in one place.
hypervisor
Package hypervisor implements the host-side half of console access to a BYOC VM host that is itself unreachable — see docs/architecture/byoc-vm-console-access.md.
Package hypervisor implements the host-side half of console access to a BYOC VM host that is itself unreachable — see docs/architecture/byoc-vm-console-access.md.
integrity
Package integrity turns a backend's own runtime state into a signed self-measurement that the control plane verifies out of band of the backend's normal reporting, to detect tampering of a backend's control plane.
Package integrity turns a backend's own runtime state into a signed self-measurement that the control plane verifies out of band of the backend's normal reporting, to detect tampering of a backend's control plane.
limitio
Package limitio caps how many bytes the daemon buffers from a source it does not control: command output and files read out of a box, and HTTP response bodies from peers, boxes and the daemon API (#3469).
Package limitio caps how many bytes the daemon buffers from a source it does not control: command output and files read out of a box, and HTTP response bodies from peers, boxes and the daemon API (#3469).
logframe
Package logframe implements the #1674 text-safe framing format shared by agent-box's writer (internal/agentbox, framed capture_mode) and the `containarium code` client's demuxer: one frame per line, "<stream> <base64(payload)>\n".
Package logframe implements the #1674 text-safe framing format shared by agent-box's writer (internal/agentbox, framed capture_mode) and the `containarium code` client's demuxer: one frame per line, "<stream> <base64(payload)>\n".
logverbcheck
Package logverbcheck keeps tenant-controlled strings from reaching logs and CLI tables unescaped (#3457, follow-up to #3455, #3456 and #3448).
Package logverbcheck keeps tenant-controlled strings from reaching logs and CLI tables unescaped (#3457, follow-up to #3455, #3456 and #3448).
mcp
metrics/cloudexport
Package cloudexport is the seam for opt-in export of Containarium's host/container infra metrics to a host cloud's native monitoring (GCP Cloud Monitoring first — #1069/#1070/#1071).
Package cloudexport is the seam for opt-in export of Containarium's host/container infra metrics to a host cloud's native monitoring (GCP Cloud Monitoring first — #1069/#1070/#1071).
metrics/platformstats
Package platformstats accumulates platform-domain facts the cloud-native metrics export platform group (#1082/#1083/#1084) observes at each export tick: API request/error counts today, provisioning outcomes and connectivity state in follow-up issues.
Package platformstats accumulates platform-domain facts the cloud-native metrics export platform group (#1082/#1083/#1084) observes at each export tick: API request/error counts today, provisioning outcomes and connectivity state in follow-up issues.
modelgateway
Package modelgateway is a prototype of the agent model gateway (docs/AGENT-MODEL-GATEWAY-DESIGN.md): a single egress point that holds the provider API key and brokers every agent box's model calls, so the key never lives in a box.
Package modelgateway is a prototype of the agent model gateway (docs/AGENT-MODEL-GATEWAY-DESIGN.md): a single egress point that holds the provider API key and brokers every agent box's model calls, so the key never lives in a box.
netbpf
Package netbpf holds the host-side plumbing for the per-tenant network isolation feature (#315, Phase A): resolving each container's host veth (so the tc-bpf TC_INGRESS program can be attached to the sender side of every flow — see docs/security/NETWORK-ISOLATION-DESIGN.md, "Phase 0 validation findings") and, on Linux, loading/attaching the BPF programs themselves.
Package netbpf holds the host-side plumbing for the per-tenant network isolation feature (#315, Phase A): resolving each container's host veth (so the tc-bpf TC_INGRESS program can be attached to the sender side of every flow — see docs/security/NETWORK-ISOLATION-DESIGN.md, "Phase 0 validation findings") and, on Linux, loading/attaching the BPF programs themselves.
netpolicy
Package netpolicy validates and compiles per-tenant NetworkPolicy values (the Phase A control-plane half of the eBPF network-isolation design) into the normalized form the per-veth TC_INGRESS BPF loader consumes.
Package netpolicy validates and compiles per-tenant NetworkPolicy values (the Phase A control-plane half of the eBPF network-isolation design) into the normalized form the per-veth TC_INGRESS BPF loader consumes.
nicguard
Package nicguard holds what the two Incus NIC-ACL guards share: the arming mode and its parser, the firewall-driver precondition, the bridge parser, and the create-or-update-on-drift ACL writer.
Package nicguard holds what the two Incus NIC-ACL guards share: the arming mode and its parser, the firewall-driver precondition, the bridge parser, and the create-or-update-on-drift ACL writer.
notify
Package notify pushes a waiting `code run --approvals ask` permission request to the developer's phone through ntfy (#2185).
Package notify pushes a waiting `code run --approvals ask` permission request to the developer's phone through ntfy (#2185).
policyreadiness
Package policyreadiness reports whether the daemon's policy stores are ready (#2483).
Package policyreadiness reports whether the daemon's policy stores are ready (#2483).
poolcapacity
Package poolcapacity watches Incus storage-pool fill (#2823).
Package poolcapacity watches Incus storage-pool fill (#2823).
proofpack
Package proofpack generates a Proof Pack: the repository's declared test commands, run by the platform inside a box, with each command's exit status and output recorded and digested (docs/PROOF-PACK.md, #2797).
Package proofpack generates a Proof Pack: the repository's declared test commands, run by the platform inside a box, with each command's exit status and output recorded and digested (docs/PROOF-PACK.md, #2797).
releasecheck
Package releasecheck reports the latest Containarium release published on GitHub, cached server-side so a busy fleet's status checks don't burn the unauthenticated GitHub rate limit (~60/hr).
Package releasecheck reports the latest Containarium release published on GitHub, cached server-side so a busy fleet's status checks don't burn the unauthenticated GitHub rate limit (~60/hr).
releases
Package releases fetches the project's latest published GitHub release and caches it, so operators can see "a newer version is available" without every page load burning GitHub's unauthenticated rate limit (60 req/h/IP).
Package releases fetches the project's latest published GitHub release and caches it, so operators can see "a newer version is available" without every page load burning GitHub's unauthenticated rate limit (60 req/h/IP).
reqrate
Package reqrate computes per-container HTTP request rates from the Caddy edge's structured (JSON) access log — the source for #231's request-rate plane.
Package reqrate computes per-container HTTP request rates from the Caddy edge's structured (JSON) access log — the source for #231's request-rate plane.
retention
Package retention stores the per-class retention policy and the per-org legal holds (#2576, slice A #2875; docs/security/DATA-FLOW-AND-RETENTION.md).
Package retention stores the per-class retention policy and the per-org legal holds (#2576, slice A #2875; docs/security/DATA-FLOW-AND-RETENTION.md).
retention/pgstore
Package pgstore is the Postgres retention.Store.
Package pgstore is the Postgres retention.Store.
retention/storetest
Package storetest is the behavioural contract every retention.Store must meet.
Package storetest is the behavioural contract every retention.Store must meet.
runlease
Package runlease implements the pure lifecycle of a run's credentials.
Package runlease implements the pure lifecycle of a run's credentials.
runlog
Package runlog is the client side of TailRunLog (#2096): the one Go function `containarium crew logs` and the MCP `crew_logs` tool both call.
Package runlog is the client side of TailRunLog (#2096): the one Go function `containarium crew logs` and the MCP `crew_logs` tool both call.
runner
Package runner provisions Containarium boxes as ephemeral GitHub Actions self-hosted runners.
Package runner provisions Containarium boxes as ephemeral GitHub Actions self-hosted runners.
safecast
Package safecast provides overflow-safe integer conversions.
Package safecast provides overflow-safe integer conversions.
sandbox/dialer
Package dialer caches gRPC connections to agent-box's resident SpawnService, one per pool member's bind-mounted unix socket (#1488 Phase 2/3).
Package dialer caches gRPC connections to agent-box's resident SpawnService, one per pool member's bind-mounted unix socket (#1488 Phase 2/3).
sandbox/ipam
Package ipam allocates static IPv4 addresses for pool members (#1488 Phase 3): "Pool members get a statically allocated IP from a per-host IPAM range at warm time...
Package ipam allocates static IPv4 addresses for pool members (#1488 Phase 3): "Pool members get a statically allocated IP from a per-host IPAM range at warm time...
sandbox/pool
Package pool implements the warm-pool reconciler and claim ring for ephemeral sandboxes (#1488 Phase 3): "Pool members are created and started by a background reconciler.
Package pool implements the warm-pool reconciler and claim ring for ephemeral sandboxes (#1488 Phase 3): "Pool members are created and started by a background reconciler.
sandbox/ratelimit
Package ratelimit implements the per-tenant spawn rate limiter for SandboxServer.SpawnSandbox (#1488 Phase 4: "per-tenant rate limit").
Package ratelimit implements the per-tenant spawn rate limiter for SandboxServer.SpawnSandbox (#1488 Phase 4: "per-tenant rate limit").
secrets
Package secrets implements the daemon-side Postgres-backed store for tenant secrets, layered on top of pkg/core/secrets crypto.
Package secrets implements the daemon-side Postgres-backed store for tenant secrets, layered on top of pkg/core/secrets crypto.
sentinel/anondoor
Package anondoor is the sshpiperd plugin behind `ssh new.<cloud-domain>` (docs/architecture/ssh-new-anonymous-box.md, #2198): the sentinel-side half of the anonymous-box door.
Package anondoor is the sshpiperd plugin behind `ssh new.<cloud-domain>` (docs/architecture/ssh-new-anonymous-box.md, #2198): the sentinel-side half of the anonymous-box door.
sentinel/sshauthz
Package sshauthz implements the sentinel's audit-only live SSH check.
Package sshauthz implements the sentinel's audit-only live SSH check.
sentinel/sshban
Package sshban owns the sentinel SSH plugin's live source-IP failure budget.
Package sshban owns the sentinel SSH plugin's live source-IP failure budget.
sentinel/sshcontrol
Package sshcontrol shares guarded SSH setup admission across local plugins.
Package sshcontrol shares guarded SSH setup admission across local plugins.
sentinel/sshgate
Package sshgate provides bounded, shared admission for backend SSH setup.
Package sshgate provides bounded, shared admission for backend SSH setup.
sentinel/sshsession
Package sshsession implements containarium#1980: a structured session lifecycle record for SSH connections accepted by the sentinel's sshpiperd.
Package sshsession implements containarium#1980: a structured session lifecycle record for SSH connections accepted by the sentinel's sshpiperd.
sentinel/sshupstream
Package sshupstream exposes the sentinel's selected-routing transport hook.
Package sshupstream exposes the sentinel's selected-routing transport hook.
sshauthz
Package sshauthz contains the daemon-side SSH authorization decision seam.
Package sshauthz contains the daemon-side SSH authorization decision seam.
sshconfig
Package sshconfig generates a self-contained OpenSSH config file for every container the user can reach.
Package sshconfig generates a self-contained OpenSSH config file for every container the user can reach.
sshkey
Package sshkey detects, generates, and fingerprints local SSH keypairs for the `containarium ssh setup` flow (sub-task A5 of umbrella-issue #100).
Package sshkey detects, generates, and fingerprints local SSH keypairs for the `containarium ssh setup` flow (sub-task A5 of umbrella-issue #100).
storageprobe
Package storageprobe measures whether one tenant's writeback stalls another tenant's fsync on a shared backend.
Package storageprobe measures whether one tenant's writeback stalls another tenant's fsync on a shared backend.
tenantguard
Package tenantguard computes and reconciles the network ACLs that keep one tenant's containers off another tenant's containers on a shared Incus bridge.
Package tenantguard computes and reconciles the network ACLs that keep one tenant's containers off another tenant's containers on a shared Incus bridge.
testsupport/incusenv
Package incusenv asserts that a real, usable Incus is present before an Incus-backed integration test runs, and decides what to do when one is not (#1332).
Package incusenv asserts that a real, usable Incus is present before an Incus-backed integration test runs, and decides what to do when one is not (#1332).
testsupport/postgres
Package postgres isolates PostgreSQL-backed test binaries.
Package postgres isolates PostgreSQL-backed test binaries.
threatdetect
Package threatdetect holds the background security-detection engine: the rule registry, the finding store, and delivery.
Package threatdetect holds the background security-detection engine: the rule registry, the finding store, and delivery.
tokenid
Package tokenid is the shared leaf for what a token issuer must keep to revoke a token it issued: the jti and its expiry.
Package tokenid is the shared leaf for what a token issuer must keep to revoke a token it issued: the jti and its expiry.
toolaccess
Package toolaccess is the one mapping between the BoxToolAccess proto enum and the string stored in the user.containarium.tool_access Incus config key (#2944).
Package toolaccess is the one mapping between the BoxToolAccess proto enum and the string stored in the user.containarium.tool_access Incus config key (#2944).
tracker
Package tracker will hold the daemon-side tracker broker — agent-visible GitHub/GitLab issue and change-request verbs backed by a daemon-custody credential (#1920).
Package tracker will hold the daemon-side tracker broker — agent-visible GitHub/GitLab issue and change-request verbs backed by a daemon-custody credential (#1920).
tracker/github
Package github translates internal/tracker's provider-neutral verbs to the GitHub REST API.
Package github translates internal/tracker's provider-neutral verbs to the GitHub REST API.
tracker/gitlab
Package gitlab translates internal/tracker's provider-neutral verbs to the GitLab REST API (v4).
Package gitlab translates internal/tracker's provider-neutral verbs to the GitLab REST API (v4).
tracker/submit
Package submit implements #1923's "no push credential in the box" change submission path: extracting a git bundle from the box, pushing it from a fresh temporary bare repository on the host, and handing the result to a provider adapter's OpenChange.
Package submit implements #1923's "no push credential in the box" change submission path: extracting a git bundle from the box, pushing it from a fresh temporary bare repository on the host, and handing the result to a provider adapter's OpenChange.
transfer
Package transfer ships files from the local workstation into a remote Containarium container, via the same SSH path the demo flow uses (laptop → sentinel → sshpiper → backend → containarium-shell → incus exec).
Package transfer ships files from the local workstation into a remote Containarium container, via the same SSH path the demo flow uses (laptop → sentinel → sshpiper → backend → containarium-shell → incus exec).
ttlsweeper
Package ttlsweeper enforces per-container TTLs by ticking once a minute and force-deleting any container whose ttl_expires_at has elapsed.
Package ttlsweeper enforces per-container TTLs by ticking once a minute and force-deleting any container whose ttl_expires_at has elapsed.
waf
Package waf is the Tier 3 (#662) userspace-WAF-behind-eBPF-steering slice.
Package waf is the Tier 3 (#662) userspace-WAF-behind-eBPF-steering slice.
wake
Package wake implements the "wake-on-HTTP" piece of the auto-sleep feature: when an auto-sleeping container's HTTP route is hit, Caddy proxies the request to the daemon's wake handler, the handler starts the container and waits until it's ready, then proxies the request through.
Package wake implements the "wake-on-HTTP" piece of the auto-sleep feature: when an auto-sleeping container's HTTP route is hit, Caddy proxies the request to the daemon's wake handler, the handler starts the container and waits until it's ready, then proxies the request through.
zap
pkg
core/backup
Package backup implements logical (pg_dump) database backups for the databases running inside Containarium containers, stored off the database host.
Package backup implements logical (pg_dump) database backups for the databases running inside Containarium containers, stored off the database host.
core/box
Package box defines the runtime-neutral seam between the daemon and the substrate a box runs on.
Package box defines the runtime-neutral seam between the daemon and the substrate a box runs on.
core/box/k8s
Package k8s implements box.BoxBackend on Kubernetes, declaring one kubernetes-sigs/agent-sandbox Sandbox CR per box: a per-tenant pod an agent reaches over SSH, serving the same agent-box stdio MCP surface as the LXC backend.
Package k8s implements box.BoxBackend on Kubernetes, declaring one kubernetes-sigs/agent-sandbox Sandbox CR per box: a per-tenant pod an agent reaches over SSH, serving the same agent-box stdio MCP surface as the LXC backend.
core/box/k8s/boxmeta
Package boxmeta holds the labels and names that identify a K8s box's Kubernetes objects.
Package boxmeta holds the labels and names that identify a K8s box's Kubernetes objects.
core/box/lxc
Package lxc implements box.BoxBackend over the existing LXC/incus container.Manager.
Package lxc implements box.BoxBackend over the existing LXC/incus container.Manager.
core/catalogsig
Package catalogsig provides an optional, offline provenance check for external skill/crew catalogs loaded from disk (#648).
Package catalogsig provides an optional, offline provenance check for external skill/crew catalogs loaded from disk (#648).
core/cluster
Package cluster provisions and reconciles managed-Kubernetes-cluster VMs (#1414): a platform-owned k3s control-plane VM plus worker VMs in typed size classes, driven over the Incus API.
Package cluster provisions and reconciles managed-Kubernetes-cluster VMs (#1414): a platform-owned k3s control-plane VM plus worker VMs in typed size classes, driven over the Incus API.
core/container
Package container provides the high-level container lifecycle Manager used by both the OSS daemon and any future cloud daemon: create, start, stop, delete, resize, label, plus jump-server SSH provisioning and collaborator-account management.
Package container provides the high-level container lifecycle Manager used by both the OSS daemon and any future cloud daemon: create, start, stop, delete, resize, label, plus jump-server SSH provisioning and collaborator-account management.
core/crews
Package crews provides the built-in catalog of crews.
Package crews provides the built-in catalog of crews.
core/expose
Package expose holds the business logic for "make a container port reachable on a public hostname." Both the `containarium expose-port` CLI subcommand and the platform MCP's `expose_port` tool delegate to this package — the CLI is the canonical surface, and the MCP tool is a thin wrapper around the same Run() function via a transport-specific adapter implementing APIClient.
Package expose holds the business logic for "make a container port reachable on a public hostname." Both the `containarium expose-port` CLI subcommand and the platform MCP's `expose_port` tool delegate to this package — the CLI is the canonical surface, and the MCP tool is a thin wrapper around the same Run() function via a transport-specific adapter implementing APIClient.
core/incus
Package incus wraps the Incus/LXC API used to drive container lifecycle, networking, and storage on a Containarium host.
Package incus wraps the Incus/LXC API used to drive container lifecycle, networking, and storage on a Containarium host.
core/incus/incustest
Package incustest provides test doubles for the incus package.
Package incustest provides test doubles for the incus package.
core/network
Package network provides network primitives for Containarium hosts: passthrough TCP/UDP routing via iptables, port-forwarding setup, and PostgreSQL-backed persistence of route definitions.
Package network provides network primitives for Containarium hosts: passthrough TCP/UDP routing via iptables, port-forwarding setup, and PostgreSQL-backed persistence of route definitions.
core/nodevm
Package nodevm provisions Incus VMs that each become a Containarium backend ("node") — carving one physical host into multiple pool-tagged nodes (e.g.
Package nodevm provisions Incus VMs that each become a Containarium backend ("node") — carving one physical host into multiple pool-tagged nodes (e.g.
core/ospkg
Package ospkg abstracts over Linux package managers (apt on Debian / Ubuntu, dnf on RHEL / Fedora) so installer logic can target a single PackageManager interface regardless of the container's OS family.
Package ospkg abstracts over Linux package managers (apt on Debian / Ubuntu, dnf on RHEL / Fedora) so installer logic can target a single PackageManager interface regardless of the container's OS family.
core/ostype
Package ostype detects the OS family of a container (Debian, RHEL, etc.) and maps Containarium's logical OSType to concrete Incus image names.
Package ostype detects the OS family of a container (Debian, RHEL, etc.) and maps Containarium's logical OSType to concrete Incus image names.
core/pki
Package pki implements the Containarium peer-CA used to issue short-lived certificates for sentinel↔daemon and peer-to-peer HTTPS.
Package pki implements the Containarium peer-CA used to issue short-lived certificates for sentinel↔daemon and peer-to-peer HTTPS.
core/recipes
Package recipes provides the built-in catalog of declarative GPU/app recipes.
Package recipes provides the built-in catalog of declarative GPU/app recipes.
core/sdlcskills
Package sdlcskills holds the pins for skill sources shipped in coding-agent boxes (#2065, #3048): each repository commit and the sha256 of its deterministic tarball.
Package sdlcskills holds the pins for skill sources shipped in coding-agent boxes (#2065, #3048): each repository commit and the sha256 of its deterministic tarball.
core/secrets
Package secrets implements the daemon-side cryptographic primitives for storing and retrieving tenant secrets per the design in docs/SECRETS-MANAGEMENT-DESIGN.md.
Package secrets implements the daemon-side cryptographic primitives for storing and retrieving tenant secrets per the design in docs/SECRETS-MANAGEMENT-DESIGN.md.
core/skills
Package skills provides the built-in catalog of agent skills.
Package skills provides the built-in catalog of agent skills.
core/sshdpolicy
Package sshdpolicy is the single source of truth for the SSH-server policy Containarium applies inside every box (#2424): the managed drop-in that turns password authentication off, and the pure evaluation of an sshd configuration against that policy.
Package sshdpolicy is the single source of truth for the SSH-server policy Containarium applies inside every box (#2424): the managed drop-in that turns password authentication off, and the pure evaluation of an sshd configuration against that policy.
core/stacks
Package stacks defines reusable software stacks (Node.js, Python, etc.) that can be installed inside a Containarium container as part of provisioning.
Package stacks defines reusable software stacks (Node.js, Python, etc.) that can be installed inside a Containarium container as part of provisioning.
core/taskgraph
Package taskgraph validates a TaskGraph (#2803, slice 1 of #2369): a high-level goal decomposed into subtasks, each assigned to a crew or a skill, wired by depends-on edges.
Package taskgraph validates a TaskGraph (#2803, slice 1 of #2369): a high-level goal decomposed into subtasks, each assigned to a crew or a skill, wired by depends-on edges.
core/toolchain
Package toolchain describes the host-managed, shared build tools (#3164).
Package toolchain describes the host-managed, shared build tools (#3164).
core/volume
Package volume defines the runtime-neutral shared-volume service and the existing Incus/CephFS implementation (#384).
Package volume defines the runtime-neutral shared-volume service and the existing Incus/CephFS implementation (#384).
core/zfscrypt
Package zfscrypt drives the `zfs` CLI for per-tenant native encryption.
Package zfscrypt drives the `zfs` CLI for per-tenant native encryption.
core/zfskey
Package zfskey provides per-tenant key custody for ZFS native encryption.
Package zfskey provides per-tenant key custody for ZFS native encryption.
pb/containarium/cloud/v1
Package cloudv1 is a reverse proxy.
Package cloudv1 is a reverse proxy.
pb/containarium/v1
Package containariumv1 is a reverse proxy.
Package containariumv1 is a reverse proxy.
terraform
test
e2e/cluster
Package clustere2e is the gated KVM end-to-end lane for managed Kubernetes clusters (#1418) — the definition-of-done check for the managed-clusters MVP (design: docs/architecture/managed-k8s-clusters.md, "End-to-end" section).
Package clustere2e is the gated KVM end-to-end lane for managed Kubernetes clusters (#1418) — the definition-of-done check for the managed-clusters MVP (design: docs/architecture/managed-k8s-clusters.md, "End-to-end" section).
fixtures/ip-echo command
ip-echo is a tiny HTTP server that echoes the requester's identity.
ip-echo is a tiny HTTP server that echoes the requester's identity.
fixtures/proxyproto-relay command
proxyproto-relay is a test fixture that mimics the sentinel's HTTPS forwarding path: it accepts TCP connections, optionally prepends a PROXY v2 header (using the same encoder the sentinel uses), and pipes bytes to a backend address.
proxyproto-relay is a test fixture that mimics the sentinel's HTTPS forwarding path: it accepts TCP connections, optionally prepends a PROXY v2 header (using the same encoder the sentinel uses), and pipes bytes to a backend address.
fixtures/tier2-l4-lifecycle command
tier2-l4-lifecycle: drives a real caddy-l4 server through the operations the daemon performs at runtime (EnableL4ProxyProtocol → ActivateL4 → AddL4Route * N → RemoveL4Route → ListL4Routes) and asserts the pattern B wrapping is intact at every step.
tier2-l4-lifecycle: drives a real caddy-l4 server through the operations the daemon performs at runtime (EnableL4ProxyProtocol → ActivateL4 → AddL4Route * N → RemoveL4Route → ListL4Routes) and asserts the pattern B wrapping is intact at every step.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL