Berry Wiki

Containarium

Properties2
tagsai, sandboxing
aliasesContainarium

8 min read

Containarium

Summary

Containarium is a self-hosted platform that gives AI agents persistent Linux environments. It uses Incus/LXC system containers by default, offers an experimental Kubernetes backend, and exposes management through SSH, command line, APIs, a web interface, and Model Context Protocol (MCP) tools.

  • Repository: FootprintAI/Containarium
  • Implementation: Go
  • License: Apache-2.0
  • Latest release: v0.51.5
  • Checked: 2026-07-14

Problem

Agents often need a long-lived Linux machine where they can install packages, run services, and publish test applications. Giving them a laptop or cluster credentials creates too much access. Containarium provides remotely reachable boxes with a separate management plane and tenant ownership.

How It Works

  • Default runtime: A daemon creates persistent Incus/LXC system containers on a Linux host.
  • Agent access: SSH routes to a container through sshpiper; the agent does not need an Incus or Kubernetes control-plane credential.
  • In-box tools: agent-box exposes bounded-output shell and file operations over MCP.
  • Platform tools: A second MCP server and the CLI create, start, stop, delete, inspect, and expose containers.
  • Sentinel: An optional front VM holds stable SSH/HTTPS entry points and routes traffic to backend hosts.
  • Public apps: Caddy terminates TLS and forwards a selected hostname to a container port.
  • Persistence: Containers are intended to survive agent sessions and host restarts; optional ZFS supports storage and snapshots.

Security Boundary

The main runtime boundary is an LXC system container. It has its own users, filesystem, process namespace, and network namespace, but shares the Linux host kernel.

Implemented security layers include:

  • SSH keys instead of giving agents host or cluster-control credentials;
  • per-owner authorization and scoped JSON Web Tokens for the control API;
  • optional eBPF policies on Incus container network interfaces;
  • Kubernetes pods with service-account token mounting disabled and restricted pod-security settings;
  • optional image-digest, registry, key-management, audit, and telemetry controls.

Critical defaults and limits:

  • Network enforcement is off by default: Loading the eBPF program is one opt-in; actual packet dropping requires a second opt-in plus an enforce-mode tenant policy.
  • LXC shares the host kernel: A kernel/container escape can cross the boundary.
  • Agent-box is broad: shell_exec runs arbitrary commands. Its file-root restriction is optional and unset by default.
  • Security controls are mostly opt-in: The README says they default off for upgrade safety.
  • Public exposure adds risk: SSH, HTTPS, routing, tokens, and tunnels must all be operated securely.

Platforms And Agents

  • Host: Linux; the quick start expects a fresh Ubuntu VM and installs Incus.
  • Guest distributions: Ubuntu 24.04 is default; Rocky Linux 9 and RHEL 9 are described for testing/production.
  • Experimental runtime: Kubernetes StatefulSets in per-tenant namespaces.
  • Windows: Documentation describes Windows Server VMs through QEMU/KVM, but this is not the main LXC agent-box path.
  • Agents: Any SSH or MCP-capable client; examples name Claude Code, Cursor, and OpenCode.
  • GPU: NVIDIA GPU passthrough is claimed for suitable bare-metal hosts and Kubernetes resource limits.

Setup

The official quick start runs a remote install script as root on a fresh Ubuntu VM. It installs Containarium, Incus, and dependencies, then starts an API on localhost port 8080.

After installation:

  1. Create a box with an SSH public key.
  2. Generate SSH configuration and include it from the user’s SSH config.
  3. Point an MCP-capable agent at ssh <box> agent-box.
  4. Optionally expose a container port through a public hostname.

The Kubernetes backend can be selected with a daemon flag or configuration variable. Production use requires more operator work for authentication, routing, databases, key management, observability, backups, and network policy.

Network And Credentials

  • Agent credential: The normal container access path uses a tenant SSH key.
  • Control API: Uses scoped access/refresh tokens with issuer, audience, and token identifiers.
  • Egress policy: Incus hosts can use eBPF CIDR and resolved-domain allow-lists; cloud metadata is denied by default when enforcement is active.
  • Enforcement startup: The daemon continues without enforcement if the eBPF object fails to load.
  • Kubernetes networking: The docs describe default-deny Kubernetes NetworkPolicy; this is distinct from the Incus eBPF path.
  • Secrets: The architecture describes PostgreSQL storage with optional envelope encryption through Vault Transit or Google Cloud KMS.
  • Container secrets: Runtime secrets may be mounted under /run/secrets on temporary memory storage with limited permissions.
  • Public routing: The sentinel can expose SSH and HTTPS and route by username or hostname.

Strengths

  • Persistent full Linux: Better suited than process sandboxes for package installs, system services, databases, and reboots.
  • No cluster token for agent: SSH and in-box MCP separate agent work from infrastructure administration.
  • Self-hosted: Teams can keep compute and code on their own infrastructure.
  • Multiple control surfaces: CLI, MCP, SSH, REST, gRPC, and web UI support different workflows.
  • Tenant-aware design: Ownership, authorization, routing, network policy, and audit features target shared deployments.
  • Public service workflow: A container service can receive a managed hostname and TLS route.
  • Active validation: The repository includes tests and backend validation notes for eBPF enforcement.

Limits

  • Operational weight: Incus, sentinel routing, databases, TLS, KMS, and optional Kubernetes make this a platform to operate, not a small local wrapper.
  • Shared-kernel isolation: LXC is lighter than a VM but provides a smaller boundary from the host.
  • Safe defaults are incomplete: Important security features must be explicitly enabled.
  • Kubernetes backend is experimental: Feature parity should not be assumed.
  • Agent MCP is not inherently safe: Typed tools include arbitrary shell execution, and the file root is unrestricted unless configured.
  • eBPF requirements: The main path needs a compatible Linux kernel and correct object loading; enforcement can fail open by remaining disabled.
  • Young project: High commit volume does not replace long-term production evidence or an independent audit.

Unsupported Or Overstated Claims

  • “No cross-tenant leakage”: This is an absolute marketing claim. The repository shows controls, but no formal proof or independent audit establishes zero leakage.
  • “Typed, bounded, safe” MCP: Output and time are bounded, but shell_exec is arbitrary and file scoping defaults off. MCP typing does not make commands safe.
  • Portable eBPF across LXC and Kubernetes: The checked eBPF enforcer directly inspects Incus containers and host virtual interfaces. Kubernetes is documented with NetworkPolicy. The claim of one portable eBPF allow-list across both backends was not established.
  • “Hardened” Kubernetes foothold: Restricted pod settings and no service-account token are useful, but “hardened” is not backed by a cited audit or benchmark.
  • Production labels: RHEL is called production-ready and several enterprise controls are described, but no service-level guarantees, certification, or production case study was found.

Activity And Maturity

Checked 2026-07-14:

  • Created: 2025-12-28.
  • Latest release: v0.51.5, published 2026-07-14.
  • Latest checked commit: 7980159a72a7, dated 2026-07-14.
  • History: About 1,005 commits.
  • Interest: 258 stars and 17 forks.
  • Open work: 28 combined visible issues and pull requests at the API check.
  • Assessment: Highly active pre-1.0 platform with substantial code and documentation, but broad scope, opt-in security, and limited independent evidence.

Best Fit

Best for a team willing to operate Linux infrastructure that needs persistent, SSH-reachable agent environments, public preview services, tenant ownership, and API/MCP automation.

It is excessive for one developer who only wants to protect a laptop. It is also a poor fit where VM-grade tenant isolation, turnkey secure defaults, or audited production controls are required.

Comparison

  • Versus Clawk: Containarium is a persistent, remotely hosted multi-tenant platform. Clawk is a local disposable VM workflow with simpler default network restriction.
  • Versus Flar: Containarium supplies whole system containers and infrastructure APIs. Flar is a lightweight Linux process sandbox using the host toolchain.
  • Versus Incus alone: It adds agent MCP tools, SSH routing, ownership, APIs, public exposure, audit, secrets, and optional eBPF policy.
  • Versus cloud sandbox services: It is self-hosted and open source, but the operator owns deployment, security, upgrades, and availability.
  • Versus Kubernetes agent runtimes: It emphasizes SSH without agent-held cluster credentials and offers an Incus backend, while its Kubernetes path remains experimental.

HN Context

Containarium appeared twice in the Clawk discussion. A commenter proposed LXC plus eBPF as a lighter alternative to VMs and said that was Containarium’s approach. Another called it lightweight, portable, MCP-enabled, and eBPF-secured.

The repository supports the broad direction: Incus/LXC is the main runtime, MCP tools exist, and eBPF enforcement code is present and validated on a Linux backend. The HN summaries omit the important caveat that eBPF observation and packet dropping are both opt-in, while the Kubernetes backend is experimental.

Unknowns

  • Audit: No independent security audit or penetration-test report was found.
  • Production adoption: Public production case studies and reliability data were not found.
  • Backend parity: Exact LXC/Kubernetes feature parity is unclear.
  • Failure behavior: Some security setup failures log and continue; the complete fail-open matrix is not summarized in one document.
  • Windows maturity: The Windows VM path appears separate and its integration parity was not established.

Sources

Graph View