Docs / Hotcell

Hotcell

Hotcell runs isolated sandboxes for AI agents on your own hardware: one daemon, three drivers, a CLI, SDKs and a gateway that keeps keys on the host.

Hotcell is self-hostable sandbox infrastructure for AI agents. You run one daemon on a machine you control (a Mac Mini, a cloud VM, a bare-metal server) and it gives you as many isolated sandboxes as that machine can hold. Provider API keys stay on the host: sandboxes reach LLMs and GitHub through a gateway that swaps a per-sandbox token for the real key.

Hotcell is open source under the Apache-2.0 license. Source: github.com/directionally-local/hotcell.

If you just want coding agents that run in Hotcell sandboxes, install Directionally Local (npm install -g directionallylocal, then dl; see /docs/install/). It sets up Hotcell and Autopilot for you.

What you get

  • Sandboxes with a /workspace volume that survives stop, start and daemon restarts.
  • Exec with streamed stdout and stderr, persistent sessions, background processes, file operations and file watching.
  • Preview URLs for ports inside a sandbox, and a stateful code interpreter for Python and JavaScript.
  • Lifecycle control: idle auto-pause, explicit pause and resume (a memory snapshot on microVM drivers), backups and warm pools.
  • Resource limits and admission control: per-sandbox memory, CPU and PID caps, and a host memory budget that refuses new sandboxes (HTTP 503) instead of over-subscribing the machine.
  • An egress control plane: per-sandbox gateway tokens, spend caps, model and provider allowlists, rate limits and optional default-deny networking.
  • Observability: per-sandbox CPU, memory, network and cost metrics, OpenTelemetry traces, an audit log and a web dashboard with a live terminal.

Architecture

 hotcell CLI      @hotcell/sdk (TS)      hotcell (Python)      dashboard
      \                 |                      |                  /
       +----------------+---------- REST + WebSocket -------------+
                                    |
                               hotcelld (daemon)
        SQLite state, idle reaper, metrics sampler, admission control,
        preview proxy (:4751), egress gateway (:4752), driver router
                                    |
          +-------------------------+--------------------------+
          |                         |                          |
   container driver          firecracker driver          applevz driver
   (Docker, Linux + macOS)   (Linux + KVM microVM)       (macOS microVM)

Daemon

hotcelld is a single control-plane process per host. It serves a hand-rolled node:http REST API and WebSocket on 127.0.0.1:4750 by default, stores state in embedded SQLite (~/.hotcell/state.db), and runs the idle reaper, metrics sampler, preview-URL proxy and egress gateway. hotcell start launches it in the background; for a long-running service you run hotcelld under a process manager.

Drivers

The runtime driver is the core abstraction. Every sandbox operation (create, exec, files, terminal, ports, backups, stats) goes through one interface, so the daemon, SDKs and CLI are the same whichever isolation tier you use. Three drivers ship:

Driver Isolation Host
container Docker container, shared host kernel Linux and macOS
firecracker Firecracker microVM, own kernel Linux with KVM
applevz Apple Virtualization microVM, own kernel macOS on Apple Silicon

You set a daemon-wide default with HOTCELL_DRIVER and can override it per sandbox, so one daemon can run containers and microVMs side by side. See Drivers.

Clients

  • CLI (hotcell, also installed as hc): daemon control, sandbox management, provider keys and a full-screen fleet monitor. See CLI reference.
  • TypeScript SDK (@hotcell/sdk): zero runtime dependencies. Its surface mirrors the Cloudflare Sandbox SDK.
  • Python SDK (hotcell on PyPI): standard library only.
  • Mastra provider (@hotcell/mastra): a Mastra Workspace sandbox provider.

See SDK reference and REST API reference.

Dashboard

The daemon serves a single-page dashboard at http://127.0.0.1:4750/: the sandbox list, live CPU, memory and network with sparklines, the cost meter, preview links, a live terminal, and create, stop, start and destroy. See Observability.

Ports

Port Purpose Variable
4750 REST API, WebSocket terminal, dashboard HOTCELL_PORT
4751 Preview-URL proxy HOTCELL_PROXY_PORT
4752 Egress gateway HOTCELL_EGRESS_PORT

Security model in one paragraph

Hotcell is single-tenant. The API runs arbitrary commands inside sandboxes, so anyone who can reach it controls them: treat API access as shell access. The API always requires a key, binds to loopback by default, and rejects cross-site browser requests. The container driver shares the host kernel; use a microVM driver for hardware isolation. See Self-hosting and auth.

Next steps