Docs / Hotcell / Configuration

Configuration

Every HOTCELL_* environment variable the daemon, CLI and SDKs read, with defaults, plus the config file and precedence rules.

Where settings come from

Set variables before hotcell start (the daemon inherits them) or on hotcelld directly. You can also persist them in ${HOTCELL_HOME:-~/.hotcell}/config.json, written by hotcell setup or by hand, as env-style keys with string values:

{
  "HOTCELL_HOST": "0.0.0.0",
  "HOTCELL_EGRESS_ENFORCE": "true"
}

Precedence, highest first:

  1. HOTCELL_* environment variables
  2. Legacy SBX_* environment variables (the project's former name)
  3. The config file
  4. Built-in defaults

A malformed config file is reported and ignored. Because the file can hold secrets, the daemon removes group and other permissions from it. The CLI also reads HOTCELL_API_KEY and HOTCELL_PORT from the file.

Paths

HOTCELL_HOME (default ~/.hotcell) holds config.json, api-key and keys.json. State files below default to ~/.hotcell/... (or ~/.sbx/... if only a legacy directory exists); each has its own variable.

API and core

Variable Default Description
HOTCELL_HOST 127.0.0.1 REST API bind address.
HOTCELL_PORT 4750 REST API port.
HOTCELL_API_KEY generated Key the API requires. When unset, the daemon generates one in ${HOTCELL_HOME}/api-key (0600).
HOTCELL_ALLOWED_HOSTS none Extra Host values accepted on a loopback bind (comma-separated).
HOTCELL_MAX_BODY_BYTES 33554432 Max request body size (REST and egress) before 413.
HOTCELL_DRIVER container Default driver: container, firecracker or applevz.
HOTCELL_IMAGE ghcr.io/sinameraji/hotcell-base:latest Default sandbox image.
HOTCELL_DB ~/.hotcell/state.db SQLite state. :memory: for an ephemeral store.
HOTCELL_BACKUP_DIR ~/.hotcell/backups Backup tarballs.

Resources and admission

Variable Default Description
HOTCELL_DEFAULT_MEMORY_MB 0 (unlimited) Default per-sandbox memory cap in MiB.
HOTCELL_DEFAULT_CPUS 0 (unlimited) Default per-sandbox CPU cap in fractional cores.
HOTCELL_DEFAULT_PIDS 0 (unlimited) Default per-sandbox process cap.
HOTCELL_ADMISSION enforce off only reports capacity instead of rejecting creates.
HOTCELL_HOST_MEMORY_MB 0 (auto-detect) Host memory budget for admission.
HOTCELL_HOST_CPUS 0 (auto-detect) Host CPU budget for the capacity view.
HOTCELL_OVERCOMMIT 1 Memory overcommit factor applied to the budget.
HOTCELL_DEFAULT_RESERVATION_MB 256 Admission charge for an uncapped sandbox before it is sampled.

Lifecycle

Variable Default Description
HOTCELL_SLEEP_AFTER_MS 0 (off) Default idle auto-pause timeout.
HOTCELL_REAP_INTERVAL_MS 15000 How often the idle reaper scans.
HOTCELL_CONTAINER_WARM_POOL 0 (off) Pre-started container spares for the default image and limits. Charged to admission capacity.
HOTCELL_MICROVM_BOOT_CONCURRENCY 4 Max simultaneous cold microVM boots (0 = unlimited).
HOTCELL_MICROVM_BOOT_QUEUE_TIMEOUT_MS 120000 Max wait for a boot slot (0 = unlimited).

Preview proxy

Variable Default Description
HOTCELL_PROXY_HOST 127.0.0.1 Preview proxy bind address.
HOTCELL_PROXY_PORT 4751 Preview proxy port.

Container driver

Variable Default Description
HOTCELL_AGENT_BIN packaged agent for the Docker host architecture Override the static Linux guest agent binary.
DOCKER_HOST Docker default socket Docker endpoint for colima, OrbStack, podman, remote or rootless runtimes.

Firecracker driver

Variable Default Description
HOTCELL_FC_BIN firecracker Firecracker binary.
HOTCELL_FC_KERNEL helpers/hotcell-vz/guest/vmlinux-fc in a source checkout Guest kernel (uncompressed vmlinux).
HOTCELL_FC_ROOTFS helpers/hotcell-vz/guest/rootfs.img in a source checkout Base rootfs.
HOTCELL_FC_STATE_DIR ~/.hotcell/fc Per-sandbox VM state.
HOTCELL_FC_DISK_GB 8 Default workspace disk size.
HOTCELL_FC_IMAGE_CACHE ~/.hotcell/fc/images Converted OCI-to-ext4 rootfs cache.
HOTCELL_FC_WARM_POOL 0 (off) Pre-booted spare microVMs.

Apple VZ driver

Variable Default Description
HOTCELL_VZ_HELPER_PATH in-repo build output Path to the signed hotcell-vz helper. Downloaded to ~/.hotcell/vz/ for npm installs if missing.
HOTCELL_VZ_KERNEL helpers/hotcell-vz/guest/vmlinux-vz in a source checkout Guest kernel (uncompressed arm64 Image).
HOTCELL_VZ_ROOTFS helpers/hotcell-vz/guest/rootfs.img in a source checkout Base rootfs.
HOTCELL_VZ_STATE_DIR ~/.hotcell/vz Per-sandbox VM state.
HOTCELL_VZ_DISK_GB 4 Default workspace disk size.
HOTCELL_VZ_IMAGE_CACHE ~/.hotcell/vz/images Converted rootfs cache.
HOTCELL_VZ_WARM_POOL 0 (off) Pre-booted spare microVMs.

Egress gateway

Variable Default Description
HOTCELL_EGRESS_PORT 4752 Gateway port. 0 disables the gateway.
HOTCELL_EGRESS_HOST 127.0.0.1 Gateway bind address. Set 0.0.0.0 on native Linux Docker.
HOTCELL_EGRESS_ADVERTISE_HOST host.docker.internal Host advertised in egress base URLs.
HOTCELL_KEYSTORE keychain on macOS file forces ${HOTCELL_HOME}/keys.json. The macOS keychain ignores HOTCELL_HOME, so isolated installs need file.
HOTCELL_PROVIDER_KEY_<NAME> none Provider key, for example HOTCELL_PROVIDER_KEY_OPENAI. Overrides stored keys.
HOTCELL_PROVIDER_<NAME>_BASEURL none Custom provider base URL.
HOTCELL_PROVIDER_<NAME>_AUTHHEADER none Header the provider authenticates with.
HOTCELL_PROVIDER_<NAME>_FORMAT none Header value template; {key} is replaced with the real key.
HOTCELL_MODEL_PRICES built-in table JSON file overlaid on the model price table.
HOTCELL_EGRESS_SPEND_CAP 0 (unlimited) Default per-sandbox LLM spend ceiling in USD.
HOTCELL_EGRESS_MAX_OUTPUT_TOKENS 8192 Output limit set on capped generation requests that name none.
HOTCELL_EGRESS_ENFORCE false Default-deny egress on Linux (needs CAP_NET_ADMIN). Advisory on macOS Docker.
HOTCELL_EGRESS_NETWORK hotcell-egress Bridge network name under enforcement.
HOTCELL_EGRESS_SUBNET 10.200.0.0/24 Bridge subnet under enforcement.
HOTCELL_EGRESS_DNS Docker embedded resolver Pinned DNS resolver IP under enforcement.
HOTCELL_ALLOWLIST_FILE built-in defaults JSON allowlist that replaces the defaults.
HOTCELL_ALLOWLIST_EXTRA none Extra allowed hosts (comma-separated).
HOTCELL_ALLOW_SOURCE_CONTROL true Include the GitHub, GitLab and Bitbucket allowlist tier.

Metrics and cost

Variable Default Description
HOTCELL_METRICS_INTERVAL_MS 10000 Sampler interval. 0 disables it.
HOTCELL_METRICS_HISTORY 60 Samples kept per sandbox for sparklines.
HOTCELL_COST_CPU_PER_HOUR 0.05 Cost per vCPU-hour.
HOTCELL_COST_MEM_GB_PER_HOUR 0.005 Cost per GB-hour of memory.
HOTCELL_COST_EGRESS_PER_GB 0.01 Cost per GB of preview-proxy egress.

Logs, traces and audit

Variable Default Description
HOTCELL_LOG_LEVEL info debug, info, warn or error.
HOTCELL_LOG_FORMAT pretty json for one JSON object per line.
HOTCELL_OTLP_ENDPOINT none OTLP/HTTP base URL for traces (/v1/traces) and audit logs (/v1/logs).
HOTCELL_OTLP_HEADERS none JSON object of headers for OTLP exports.
HOTCELL_OTEL_ENDPOINT, HOTCELL_OTEL_HEADERS none Legacy audit-only overrides.
HOTCELL_AUDIT_FILE ~/.hotcell/audit.jsonl Local audit log. Empty string disables it.
HOTCELL_TRACE_RING 200 Finished spans kept in memory for GET /traces.

Client variables

Variable Default Description
HOTCELL_ENDPOINT http://127.0.0.1:4750 Daemon URL for the CLI and SDKs.
HOTCELL_API_KEY local generated key API key for the CLI and SDKs.

Source: packages/daemon/src/config.ts and docs/reference.md.