Containarium v0.68.0

Caution

Superseded by v0.68.1 — do not deploy this release to a sentinel (#1598)

v0.68.0 crash-loops the containarium-sentinel service, and while looping it serves a
self-signed O=Containarium Sentinel certificate to every visitor — a
NET::ERR_CERT_AUTHORITY_INVALID browser interstitial on every HTTPS hostname the
sentinel fronts. Both production sentinels reached NRestarts of 43 and 20 within
minutes of upgrading.

The proxy-pipeline self-check sent a single TLS record-layer byte and waited to read
one back. A TLS server handed one byte of a record header correctly waits for the rest
of the ClientHello — it neither responds nor closes — so the probe timed out against a
healthy pipeline and three consecutive timeouts exited the process, roughly every two
minutes.

Use v0.68.1 instead

v0.68.1 fixes this (#1599) and contains everything below. It has been verified in
production: both sentinels ran it with zero restarts and zero self-check failures.

• Sentinels: upgrade to v0.68.1. v0.66.0 is also safe if you need to stay put.
• Primaries: unaffected by #1598 — they ran v0.68.0 with no restarts throughout.
  Everything in the notes below applies to them unchanged.

---

This release makes a box's declared CPU meaningful — throttling is now
observable and alertable, resize no longer silently discards reservations, and
host commitment is readable — and closes a class of TLS failure where a route
could serve on :80 indefinitely with no certificate.

Added

• CPU throttling counters — CFS throttling is exposed per box, so a
  throttled box is distinguishable from an idle one. Previously the two looked
  identical in metrics. (#1574)
• CPU-throttling metrics series — the throttling signal is exported, making
  it alertable rather than only readable on inspection. (#1576)
• SystemInfo.committed_cpu_cores — a read surface for a host's current CPU
  overcommit, so commitment against physical capacity can be inspected. (#1591)

Fixed

• TLS subjects are now reconciled — a route present in both the DB and Caddy
  but missing from Caddy's TLS automation policy was classified "in sync"
  forever: it served on :80 while :443 returned tls: internal error
  (alert 80, no peer certificate), with no error logged and no recovery short
  of manual admin-API surgery. RouteSyncJob now re-checks TLS subjects every
  tick and repairs them, understanding wildcard coverage so it neither leaves
  deeper hosts uncovered nor burns ACME budget duplicating the wildcard. Also
  makes a failed ProvisionTLS visible in the log instead of a bare stdout
  write. (#1589)
• ProvisionTLS fails closed on a bad policy read — a non-200 was treated
  as "this host has no policies", falling through to POST a new policy. POST
  to a Caddy array path appends, so a transient admin-API error grafted a
  duplicate policy alongside the real ones, and Caddy matches the first policy
  whose subjects match — so the duplicate could shadow the intended one. (#1593)
• Resize routes through the CPU admission gate — a resize could previously
  push a host past its committed-core ceiling without passing admission. (#1587)
• Resize no longer clobbers the K8s reservation — adds explicit cpu/memory
  request fields so a resize stops discarding the reservation it should be
  preserving. (#1577)
• K8s resize merges rather than replaces — a resize now merges into a box's
  existing resources instead of overwriting them wholesale. (#1583)

Documentation

• CPU admission gate documented as the floor mechanism — what turns a box's
  declared CPU from a ceiling into a floor. (#1592)
• CPU reservation & overcommit visibility design note. (#1578)
• Corrected two documents that claimed Caddy issues certificates on-demand. It
  does not, and never has: certificates come only from explicit TLS automation
  subjects plus the *.<base-domain> wildcard. The helloworld-python example
  in particular told readers the first request would mint a cert, which for an
  unregistered hostname yields a TLS handshake failure. (#1594)

Known limitations

• The CPU admission gate has a check-then-act race under concurrent
  operations (#1588). Two concurrent resizes/creates against the same host can
  each pass admission against a stale snapshot and jointly exceed the ceiling.
  This is pre-existing — CreateContainer has had the identical gap since
  #1029 — and is not introduced by #1587 or #1579. Called out here because two
  changes in this release concern that gate and could otherwise imply it is now
  airtight under concurrency. It is not.

• The TLS reconciliation in #1589 is forward-looking. A host already stuck
  without a certificate is repaired only once it runs a build containing this
  release; the fix does not reach back into deployments running older daemons.

• #1592's K8s CPU-request wording is superseded. A follow-up correction
  (#1595) landed on main shortly after this release's commit was verified
  and is therefore not included here. It is documentation-only; the code in
  this release is unaffected. It will ship in the next release.

Full diff: v0.67.0...v0.68.0

---

Containarium v0.68.0

The open-source, self-hostable, agent-native sandbox.

Binaries

Three binaries ship in this release:

Binary	Where it runs	What it does
containarium	The host (and your laptop, for the CLI)	The platform daemon + CLI. create, list, expose-port, ssh-config, etc.
mcp-server	Your laptop	The platform MCP — outside-the-box admin (create_container, list_containers, expose_port, list_backends). Wire it into Claude Code / Cursor.
agent-box	Inside each Containarium container	The in-the-box MCP — shell_exec, read_file, write_file, etc. Reached over stdio, typically via SSH.

Quick install (Linux host)

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

Manual install (any binary, any platform)

# containarium CLI / daemon (Linux x86_64 example)
curl -L -o /usr/local/bin/containarium \
  https://github.com/footprintai/containarium/releases/download/v0.68.0/containarium-linux-amd64
chmod +x /usr/local/bin/containarium

# Windows: client-only CLI (create/list/ssh/… against a remote daemon;
# the daemon/sentinel/tunnel subcommands are Linux/macOS only)
# PowerShell:
#   curl.exe -L -o containarium.exe `
#     https://github.com/footprintai/containarium/releases/download/v0.68.0/containarium-windows-amd64.exe

# platform MCP (your laptop, e.g. macOS arm64)
curl -L -o /usr/local/bin/mcp-server \
  https://github.com/footprintai/containarium/releases/download/v0.68.0/mcp-server-darwin-arm64
chmod +x /usr/local/bin/mcp-server

# agent-box (drop into your container image, Linux x86_64)
curl -L -o /usr/local/bin/agent-box \
  https://github.com/footprintai/containarium/releases/download/v0.68.0/agent-box-linux-amd64
chmod +x /usr/local/bin/agent-box

Verify checksums via SHA256SUMS.txt.

MCP client setup

Wire the platform MCP into Claude Code (~/.claude.json):

{
  "mcpServers": {
    "containarium": {
      "command": "/usr/local/bin/mcp-server",
      "env": {
        "CONTAINARIUM_SERVER_URL": "http://your-host:8080",
        "CONTAINARIUM_JWT_TOKEN": "<your-token>"
      }
    }
  }
}

Wire agent-box for in-the-box file/shell ops:

{
  "mcpServers": {
    "containarium-box": {
      "command": "ssh",
      "args": ["user@your-box", "agent-box"]
    }
  }
}

See README.md for the full agent-native walkthrough.