Docs / Hotcell / Self-hosting

Self-hosting and auth

Run the Hotcell daemon on a Linux VM or server: install, expose the API with a key, set up egress on Linux, and understand the security model.

The container driver uses the Docker Engine API and nothing host-specific, so a Mac Mini and a Linux cloud VM run Hotcell the same way.

Install on a Linux VM

On a fresh Ubuntu or Debian VM:

# 1. Docker (native dockerd; the daemon finds /var/run/docker.sock automatically)
curl -fsSL https://get.docker.com | sh && sudo usermod -aG docker "$USER"   # log in again

# 2. Node 22 or later, then Hotcell
node -v
npm install -g hotcell

# 3. Start the daemon. For remote access, bind a real interface and set a key.
HOTCELL_HOST=0.0.0.0 HOTCELL_API_KEY="$(openssl rand -hex 24)" hotcell start

For a long-running service, run the hotcelld binary under a process manager such as systemd instead of hotcell start. A systemd unit is also where you grant CAP_NET_ADMIN for enforced egress, for example with AmbientCapabilities=CAP_NET_ADMIN.

Authentication

The REST API always requires a key.

  • Set HOTCELL_API_KEY, or let the daemon generate one in ${HOTCELL_HOME:-~/.hotcell}/api-key (mode 0600). The local CLI and SDKs read the generated key on their own for loopback endpoints.
  • Remote clients pass the key with --api-key or HOTCELL_API_KEY (CLI), the apiKey / api_key option (SDKs), or an Authorization: Bearer or X-API-Key header (REST).
  • The dashboard asks for the key once. You can also open /dashboard#key=<key>.
  • GET /healthz, GET /info and the dashboard HTML are open, so probes work and the dashboard can prompt for the key.
export HOTCELL_ENDPOINT=http://my-server:4750
export HOTCELL_API_KEY=<key>
hotcell ls

Egress on Linux

On macOS with Docker Desktop this is handled for you. On Linux:

  • Gateway reachability. Sandboxes call the daemon at host.docker.internal, which the daemon maps to the bridge gateway. The gateway must bind somewhere the bridge can reach, and loopback isn't. Set HOTCELL_EGRESS_HOST=0.0.0.0 if you use --egress. The gateway is protected by the per-sandbox token and your VM firewall.
  • Default-deny enforcement (HOTCELL_EGRESS_ENFORCE=true) installs host DOCKER-USER iptables rules, so the daemon needs root or CAP_NET_ADMIN. Keep HOTCELL_EGRESS_ADVERTISE_HOST=host.docker.internal so the proxy and firewall agree on the gateway address. The source notes this was validated on GCP Ubuntu 24.04.
  • Non-default Docker runtimes (colima, remote, rootless): export DOCKER_HOST.

See Egress.

MicroVMs on a server

For VM-level isolation on Linux, use the firecracker driver. It needs /dev/kvm: a bare-metal server, or a cloud instance with nested virtualization. See Drivers.

Security model

Hotcell is single-tenant by design. The API runs arbitrary commands inside sandboxes, so anyone who can reach it controls them. Treat API access as shell access.

Control What it does
Bind and auth Loopback by default; the API always requires a key. Sandboxes can reach the host, so an open API would let one sandbox drive the others.
Cross-site guard Requests a browser marks as cross-site are refused, including WebSocket upgrades.
Host guard On a loopback bind, requests whose Host isn't loopback, HOTCELL_HOST or HOTCELL_ALLOWED_HOSTS are refused. This guards against DNS rebinding and localhost CSRF.
DoS bounds Request bodies are capped by HOTCELL_MAX_BODY_BYTES; WebSocket messages are size-limited.
Keys out of sandboxes Provider keys stay on the daemon; sandboxes get revocable, policy-scoped tokens. With HOTCELL_EGRESS_ENFORCE on Linux, a stolen token has nowhere to go.
Spend bounds Per-token and per-sandbox hard ceilings cap LLM cost even if a token is abused before you revoke it.
Isolation The container driver shares the host kernel; per-sandbox CPU, memory and PID caps are available. For hardware isolation, use firecracker or applevz.
Audit Lifecycle, exec, file, terminal, port, backup, auth-failure, admission, egress and key-import events are written to ~/.hotcell/audit.jsonl. See Observability.

State on disk

Path Contents
~/.hotcell/config.json Persisted configuration
~/.hotcell/api-key Generated API key (0600)
~/.hotcell/keys.json Provider keys when the keychain isn't used (0600)
~/.hotcell/state.db SQLite state; survives daemon restarts
~/.hotcell/backups/ Backup tarballs
~/.hotcell/audit.jsonl Audit log
~/.hotcell/daemon.log Daemon log when started with hotcell start
~/.hotcell/fc/, ~/.hotcell/vz/ MicroVM state and image caches

Source: docs/self-hosting.md.