Docs / Hotcell / CLI

CLI reference

Every hotcell CLI command and flag: daemon control, provider keys, sandboxes, files, processes, ports, sessions, backups and egress tokens.

The CLI is installed as hotcell and hc. Run hotcell --help for the built-in summary.

Bare hotcell in a terminal opens an interactive menu, or the setup wizard on the first run. In a non-TTY context (pipes, scripts, agents) it prints help instead, so nothing ever prompts.

Global options

Option Environment Default
--endpoint <url> HOTCELL_ENDPOINT http://127.0.0.1:4750
--api-key <key> HOTCELL_API_KEY The local daemon's generated key
-h, --help
-v, --version Shows CLI and running daemon versions and flags drift

The CLI also reads HOTCELL_API_KEY and HOTCELL_PORT from ~/.hotcell/config.json.

Daemon

Command Description
hotcell start [--foreground] [--defaults] Start the daemon in the background. The first start on a TTY shows the defaults once; --defaults skips that.
hotcell setup Guided daemon configuration (access, egress, isolation, default image), written to ~/.hotcell/config.json.
hotcell status Whether the daemon is running, on which port, and how much headroom is left.
hotcell stop Stop the daemon. Logs are in ~/.hotcell/daemon.log.
hotcell info The daemon's driver, providers, auth and cost configuration.
hotcell capacity Host memory budget, what is committed, and how many more sandboxes fit.
hotcell images [--json] Recommended base images for --image.

start and stop are overloaded by arity: with no arguments they act on the daemon; hotcell start <id> resumes a sandbox, hotcell start <id> "<cmd>" starts a background process, and hotcell stop <id> stops a sandbox.

Provider keys

Command Description
hotcell keys add <provider> [--value KEY | --stdin] Store a key on the host. Prompts with hidden input if neither flag is given. Asks for the base URL and auth header once for an unknown provider.
hotcell keys ls List stored providers.
hotcell keys rm <provider> Remove a key.
hotcell keys import [.env] [--set NAME=gateway|inject|skip] [--default-unknown gateway|inject|skip] Import a .env file, choosing a disposition for every variable. --set is repeatable.
hotcell keys review Reopen import decisions.

See Egress for what each disposition does.

Sandboxes

hotcell run

hotcell run "<cmd>" [--image I] [--keep] [--env K=V,…] [--sleep-after MS] [--egress]
            [--egress-spend-cap USD] [--memory MB] [--cpus N] [--pids N]
            [--repo URL] [--ref BRANCH] [--setup "cmd"]

Creates a sandbox, runs the command, streams the output and destroys the sandbox. --keep keeps it.

hotcell create

hotcell create [-i] [-n N] [--name HANDLE] [--image I] [--driver container|firecracker|applevz]
               [--env K=V,…] [--label K=V,…] [--sleep-after MS] [--egress] [--egress-spend-cap USD]
               [--memory MB] [--cpus N] [--pids N] [--repo URL] [--ref BRANCH] [--branch NAME]
               [--setup "cmd"] [--autopilot] [--opencode]
Flag Description
-i, --interactive Guided create (TTY only).
-n N, --count N Create N sandboxes; prints one id per line.
--name HANDLE Human handle, shown in ls and the TUI. Suffixed -1 to -N with -n.
--image I OCI image.
--driver container, firecracker or applevz.
--env K=V,… Environment variables.
--label K=V,… Labels.
--sleep-after MS Idle auto-pause timeout.
--egress Wire the sandbox to the LLM gateway.
--egress-spend-cap USD Per-sandbox LLM spend ceiling.
--memory MB, --cpus N, --pids N Hard resource caps.
--repo URL, --ref BRANCH Clone a repo into /workspace.
--branch NAME Create and check out a new branch after cloning. Bare --branch or --branch auto generates a name. With -n, a named branch is suffixed per sandbox.
--setup "cmd" Shell command run once after start. Chain steps with &&.
--autopilot Install autopilot-ai and wire it to the gateway. Implies --egress; needs an OpenRouter key and a Node-capable image.
--opencode Install OpenCode instead. Same requirements.

create shows live per-sandbox progress. Ctrl-C leaves provisioning running; check with hotcell ls.

Other sandbox commands

Command Description
hotcell ls (alias list) List sandboxes.
hotcell exec <id> "<cmd>" [--session SID] [--cwd DIR] [--env K=V,…] Run a command in a sandbox.
hotcell terminal <id> Attach an interactive shell.
hotcell tui (alias top) Full-screen fleet monitor: arrow keys to move, Enter to attach, p / r / d to pause, resume or destroy, c to create.
hotcell stats <id> Live CPU, memory and network, plus accumulated cost.
hotcell pause <id> Pause. A memory snapshot on microVM drivers.
hotcell resume <id> Resume a paused or stopped sandbox.
hotcell stop <id> Stop, keeping the workspace.
hotcell start <id> Start a stopped sandbox.
hotcell rm <id...> (alias remove), hotcell rm --all Destroy sandboxes, including workspace volumes.

Files

Command Description
hotcell files write <id> <path> --content <string> [--mode <mode>] Write a file. --mode is octal, such as 600.
hotcell files read <id> <path> Print a file.
hotcell files mkdir <id> <path> [--parents] Create a directory.
hotcell files ls <id> [path] List a directory (default /workspace).
hotcell watch <id> [path] [--interval MS] Stream created, modified and deleted events until Ctrl-C.

Processes and ports

Command Description
hotcell start <id> "<cmd>" [--cwd DIR] Start a background process.
hotcell ps <id> List background processes.
hotcell kill <id> <procId> [--signal SIG] Signal a process (default SIGTERM).
hotcell logs <id> <procId> [--follow] Stream a process's logs.
hotcell wait-port <id> <port> [--timeout MS] Block until a port is listening.
hotcell expose <id> <port> [--token TOKEN] Expose a port and print its preview URL.

Sessions and environment

Command Description
hotcell session create <id> [--cwd DIR] [--env K=V,…] [--id SID] Create a persistent session.
hotcell session ls <id> List sessions.
hotcell session rm <id> <sessionId> Delete a session.
hotcell env <id> [K=V …] Set sandbox env vars, or print them when none are given.

Code interpreter

Command Description
hotcell run-code <id> "<code>" [--lang python|javascript] Run a snippet and print its output.

Backups

Command Description
hotcell backup <id> Snapshot /workspace to a host tarball.
hotcell backups [<id>] List all backups, or one sandbox's.
hotcell restore <id> <backupId> Replace /workspace with a backup from any sandbox.

Egress tokens

hotcell egress <id> [--list] [--revoke TOKEN]
               [--ttl DUR] [--spend-cap USD] [--models CSV] [--providers CSV]
               [--rate-calls N] [--rate-tokens N] [--rate-window DUR]

With no --list or --revoke, mints a token and prints export lines for each provider. Durations take forms such as 30m, 24h or 7d. See Egress.

Flag syntax

Value flags take the next argument or --flag=value. Repeating a value flag accumulates comma-separated values, so --set A=gateway --set B=inject equals --set A=gateway,B=inject.