Quick start

This guide assumes you have installed the CLI (npm install -g hotcell) and have a Docker-compatible runtime running. See Installation.

#1. Start the daemon

hotcell

In a terminal, bare hotcell opens a guided setup on the first run, then an interactive menu. To start the daemon directly:

hotcell start              # runs in the background and returns your terminal
hotcell status             # running? which port? how much headroom?

The first hotcell start on a TTY shows the defaults once. Pass --defaults to skip that, or --foreground to keep the daemon in the foreground. Logs go to ~/.hotcell/daemon.log.

The daemon listens on http://127.0.0.1:4750 and generates an API key in ~/.hotcell/api-key. The CLI and both SDKs read that key automatically on the same machine.

#2. Run a one-shot command

hotcell run creates a sandbox, runs the command, streams the output, and destroys the sandbox:

hotcell run "python3 -c 'print(2+2)'"
hotcell run --setup "pip install ruff" "ruff check ."

Add --keep to keep the sandbox after the command finishes.

#3. Work with a persistent sandbox

id=$(hotcell create --repo https://github.com/you/app --setup "npm install")
hotcell exec "$id" "ls /workspace"
hotcell files write "$id" /workspace/hi.txt --content "hello"
hotcell files read "$id" /workspace/hi.txt
hotcell terminal "$id"     # interactive shell inside the sandbox
hotcell ls
hotcell rm "$id"

--repo clones into /workspace at create time, and --setup runs shell commands once after the sandbox starts. Setup is best-effort: a non-zero exit is logged, not fatal.

#4. Give the sandbox LLM access without your key

Store a provider key on the host, then create the sandbox with --egress:

hotcell keys add openrouter        # hidden prompt; the key stays on the host
hotcell run --egress --keep "printenv OPENROUTER_BASE_URL"
# http://host.docker.internal:4752/openrouter

Inside the sandbox, OPENROUTER_BASE_URL points at the gateway and OPENROUTER_API_KEY holds a per-sandbox token, not your key. The gateway swaps in the real key and meters the call. Cap what the sandbox can spend:

hotcell run --egress --egress-spend-cap 2 "..."

See Egress and the LLM gateway.

#5. Run several agents on one repo

hotcell create -n 5 --name feat --branch auto --autopilot \
    --repo https://github.com/you/app

This creates five sandboxes, each with the repo cloned and its own branch, and Autopilot installed and wired to the gateway. --autopilot implies --egress and needs an OpenRouter key and a Node-capable image. --opencode installs OpenCode instead.

hotcell terminal <id>      # inside: cd app && autopilot
hotcell rm --all           # destroy every sandbox; your repo is untouched

#6. Use the SDK

import { HotcellClient } from "@hotcell/sdk";

const client = new HotcellClient();             // HOTCELL_ENDPOINT / local key
const sandbox = await client.getSandbox();
const { stdout } = await sandbox.exec("python3 -c 'print(2+2)'");
await sandbox.writeFile("/workspace/hi.txt", "hello");
await sandbox.destroy();

from hotcell import HotcellClient

sandbox = HotcellClient().get_sandbox()
print(sandbox.exec("python3 -c 'print(2+2)'").stdout)   # "4\n"
sandbox.destroy()

#7. Open the dashboard

Open http://127.0.0.1:4750/. It asks for the API key once; you can also open /dashboard#key=<key>.

#Stop the daemon

hotcell stop