Installation

#Install the CLI and daemon

The hotcell npm package contains the CLI and the daemon:

npm install -g hotcell

It installs three commands:

#Node.js version

The CLI and daemon declare these Node.js engine ranges: ^22.23.4 || ^24.22.1 || >=26.12.1. The daemon needs Node 22 or later because it uses the built-in node:sqlite module and the global WebSocket.

node -v

#Install the SDKs

The SDKs talk to a running daemon. They read HOTCELL_ENDPOINT (default http://127.0.0.1:4750) and HOTCELL_API_KEY. For a loopback endpoint they also read the key the local daemon generated, so on the same machine you don't need to configure anything.

#Requirements per driver

The container driver is the default. The microVM drivers are optional and selected per sandbox or daemon-wide; see Drivers.

#Container driver (Linux and macOS)

You need a Docker-compatible runtime: Docker Desktop, native dockerd, OrbStack, colima or podman. The daemon talks to the Docker Engine API.

Native dockerd and Docker Desktop need no extra configuration. For a runtime on a non-default socket, export DOCKER_HOST before you start the daemon. Hotcell reads DOCKER_HOST, not the docker CLI's context. For colima:

export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
hotcell start

The default sandbox image is ghcr.io/sinameraji/hotcell-base:latest (Python, Node, git and build tools). Any public image works with --image; hotcell images lists a few recommended ones.

#Firecracker driver (Linux with KVM)

• A Linux host with KVM at /dev/kvm: bare metal, or a VM with nested virtualization enabled.
• The firecracker binary on PATH, or its path in HOTCELL_FC_BIN.
• A guest kernel (uncompressed vmlinux) and base rootfs. The defaults point into a source checkout (helpers/hotcell-vz/guest/). Set HOTCELL_FC_KERNEL and HOTCELL_FC_ROOTFS to use files elsewhere.
• Root or CAP_NET_ADMIN only if you opt a sandbox into a NAT network interface (networked: true). By default guests have no network device.

When the daemon starts, the driver checks for /dev/kvm and runs firecracker --version, and reports which one is missing.

#Apple VZ driver (macOS)

• macOS on Apple Silicon, with Apple Virtualization available.
• The signed hotcell-vz helper. With an npm install, the daemon downloads the ad-hoc-signed helper from the matching GitHub release into ~/.hotcell/vz/. It downloads the guest runtime (kernel, agent and image converter) on the first create. From a source checkout you build the helper with npm run build:vz.

If the helper can't be downloaded or won't run, the daemon tells you to switch to the container driver with hotcell setup or HOTCELL_DRIVER=container.

#Install from source

git clone https://github.com/directionally-local/hotcell
cd hotcell
npm install
npm run build
node packages/daemon/dist/index.js

From a source checkout, npm run smoke runs the whole surface end-to-end against Docker, and npm run smoke:py does the same through the Python SDK.

#Verify

hotcell start
hotcell status
hotcell --version    # CLI and running daemon versions; flags any drift

Next: Quick start.