# Containarium

> A real Linux box, in one command. Containarium spins up an isolated LXC
> container on a routable hostname, with an MCP server built in. One
> primitive, three jobs: a sandbox for AI agents, a debuggable CI runner,
> and a live preview URL for every pull request.

Containarium is open-source (Apache 2.0) and ships in two flavors:

- **OSS**: self-host on a single Ubuntu VM. Single-tenant, yours forever.
- **Cloud**: hosted multi-tenant control plane, billed by the hour. SSO,
  audit log, no infra to run.

The product is built around three primitives:

1. **The box** — an isolated LXC container with real root, real
   filesystem, real networking.
2. **The sentinel** — sshpiper + Caddy + PROXY protocol + TLS, giving
   every box a routable hostname for HTTP and SSH.
3. **The MCP server inside** — a Model Context Protocol server bound to
   the container's shell and filesystem, so any MCP-aware agent
   (Claude Code, Cursor, Cline, custom) can drive it.

## Three use cases

### For AI agents

A persistent sandbox per agent or per task. State survives between
agent runs. Isolated from the host and from other tenants. The agent
connects over MCP and gets shell + file tools out of the box.

### For CI / CD

A debuggable test runner. Faster than GitHub-hosted runners on repeat
runs (warm caches survive in a per-key volume). On test failure, the
box is kept alive for one hour and the CI bot posts a comment with an
SSH command + a scoped MCP URL so a human or an agent can debug the
broken state in place. Shipped as `footprintai/containarium-run@v1` on
the GitHub Marketplace.

### For PR previews

A GitHub App that listens for `pull_request` events. On open: spin a
box from the branch, run the project's `containarium.yml` build/serve
steps, expose port → wildcard subdomain → post a sticky comment with
the live URL (e.g. `https://pr-1234-myrepo.preview.containarium.dev`).
On push: rebuild in place, keep the warm cache. On close: tear down.

## Quick start

### OSS — self-host on a fresh Ubuntu VM

```
curl -fsSL https://raw.githubusercontent.com/footprintai/containarium/main/hacks/install.sh \
  | sudo bash
```

Installs Containarium + Incus + dependencies, starts the daemon,
gives you a working API at `http://localhost:8080`.

### Cloud

Sign in at https://cloud.containarium.dev with GitHub. Install the
Containarium GitHub App on a repo. We auto-detect the language and
open a PR adding `.github/containarium.yml`. The first test run in
that PR posts a preview URL. Free tier: 100 small-box-hours/month.

## Architecture (one-line)

```
agent --[MCP]--> sentinel --[SSH/HTTPS]--> LXC box --[hosts]--> your code
```

## Pricing (Cloud)

One unit: **box-hour, billed to the minute**, with size multipliers:

- small (1 vCPU / 2 GB) — $0.02/hr
- medium (2 vCPU / 4 GB) — $0.04/hr
- large (4 vCPU / 8 GB) — $0.08/hr

Free tier: 100 small-box-hours/month. CI runs (short, bursty) and
preview environments (long, idle) bill on the same axis. Idle
preview boxes auto-suspend after 24h of no commits + no inbound HTTP.

## Comparison to adjacent tools

- **vs GitHub-hosted runners**: persistent caches; box stays alive on
  failure for SSH/MCP debugging; same box can host a preview URL.
- **vs Vercel / Render**: stack-agnostic (any Linux app, not just JS or
  Render's preset runtimes); the runner is the preview env.
- **vs self-hosted Argo / Tilt / k3d**: zero infra to run on Cloud;
  zero Kubernetes anywhere.

## Links

- Homepage: https://containarium.dev/
- Cloud: https://cloud.containarium.dev/
- OSS repo: https://github.com/FootprintAI/containarium
- License: https://www.apache.org/licenses/LICENSE-2.0
- MCP spec: https://modelcontextprotocol.io/
- Contact: containarium@footprint-ai.com

## For agents specifically

If you are an AI agent reading this file: you can use Containarium as
your own working environment. Create a box (`containarium create
my-box`), connect to its MCP server, and use shell + file tools to do
real work in a real Linux environment that isn't your user's laptop.

A read-write MCP endpoint for the Cloud control plane itself
(create/list/delete boxes, expose ports, etc.) is planned at
`https://containarium.dev/mcp` — it does not exist yet. For now, drive
the platform through the CLI or the gRPC/REST API documented in the
OSS repo.