Hotcell: local sandboxes for AI agents, API keys stay on host

Hotcell is an open-source sandboxing system designed to run isolated AI agent environments on a developer's own hardware while isolating API credentials from the agents themselves. Installation is straightforward: `npm i -g hotcell`, followed by a 30-second setup on first run. The tool works with Docker, Firecracker microVMs on Linux/KVM, and Apple VZ on macOS, and automatically detects non-default Docker sockets (colima, OrbStack, podman) via the DOCKER_HOST environment variable.

The core security mechanism is credential substitution at a gateway. Developers add API keys to the host using `hotcell keys add <provider>` or bulk-import from a .env file with `hotcell keys import .env`. When a sandbox needs to make an API call, the gateway intercepts the request and swaps a short-lived per-sandbox token for the real key before forwarding it to the upstream service. This means no sandbox ever holds the actual OpenAI, GitHub, or Stripe key. The gateway protects any service whose credentials travel in HTTP request headers—OpenAI, Anthropic, OpenRouter, GitHub, Stripe, Slack, and Cloudflare are built in; additional providers can be added by specifying a base URL and auth header once in .hotcell/env.json. Sandboxes can also push to git and call LLMs without storing credentials because the gateway automatically wires git origin and LLM gateway access.

Creating sandboxes is done with commands like `hotcell create -n 5 --repo <url> --branch`, which spawns five isolated cells, each with the repository cloned, its own git branch, and optionally OpenCode (a tool for code generation) preinstalled and pointed at the gateway. Developers can open a shell inside any cell with `hotcell terminal <id>` and run one-shot commands with `hotcell run --setup "pip install ruff" "ruff check ."`, which creates a sandbox, runs the command, and tears down immediately. The daemon tracks CPU, memory, and cost per sandbox and includes admission control that refuses to over-subscribe rather than letting the system run out of memory.

The tool acknowledges what it cannot protect: credentials that do not travel in HTTP headers, such as Postgres, Redis, or MongoDB passwords (which are part of the wire handshake), AWS SigV4 signatures (signed locally before transmission), mTLS client certificates, and OAuth refresh-token flows. For these, developers must explicitly choose to inject the real value into the sandbox via `hotcell keys import .env`. The import step requires the developer to decide for each variable whether it should be swapped at the gateway, injected as the real value, or skipped entirely, and displays every value bound for the sandbox before anything is stored. An optional egress enforcement mode (kernel-enforced on Linux and microVMs, advisory on macOS Docker) denies direct calls that bypass the gateway, preventing SDKs that hardcode their endpoints from quietly circumventing the security layer. The tool is licensed under Apache-2.0 and includes benchmarks, a Python SDK (pip install hotcell), and documentation for Linux self-hosting.

Hotcell addresses a practical security gap in AI agent deployment: as teams run multiple autonomous agents on shared code repositories or across cloud infrastructure, the traditional approach of embedding API keys in sandboxes creates a large attack surface. A single compromised agent environment could expose credentials for all downstream services. Hotcell's architecture flips this by keeping credentials on the host and using a gateway to mediate all outbound calls—each sandbox holds only a temporary, narrowly-scoped token that cannot be reused or transferred.

The tool's flexibility across hardware (Mac Mini, cloud VM, bare metal) and container runtimes (Docker, Firecracker, Apple VZ) reflects the reality that different teams have different infrastructure. The admission control that refuses over-subscription instead of triggering out-of-memory errors, combined with per-cell CPU/memory/cost metering, suggests the developers have thought through the operational challenge of running dozens of agents on finite hardware without cascading failures.

A limitation the documentation acknowledges: the gateway cannot protect credentials that travel outside HTTP headers (database passwords in wire handshakes, AWS SigV4 signatures signed locally, mTLS certificates). For these, developers must choose to inject the real value into the sandbox, accepting the risk. The tool also requires that SDKs read injected base-URL environment variables; those that hardcode their endpoint will bypass the gateway unless egress enforcement denies them outright.

No comments yet. Be the first to share your thoughts!