Prerequisites

Use this checklist before you run StacyVM locally or deploy it for other developers.

Quick Checklist

Area	Required for local quickstart	Required for production
Host OS	Linux recommended, macOS acceptable for SDK/docs work	Linux host certified for the runtime you claim
Runtime	Docker for the default provider path	Docker, Firecracker, PRoot, or remote workers certified on target hosts
CLI tools	`curl`, `git`, Docker CLI	`curl`, `git`, Docker CLI, service manager, backup tooling
Build tools	Go only when building from source	Go only for source builds; release binaries are preferred
SDK tools	Python 3.9+ or Node.js 18+	Match your application language runtime
Network	Local port `7423` available	TLS, reverse proxy, exact CORS origins, private admin access
Secrets	Optional local API key	Strong API key, admin key, worker credentials where applicable
Persistence	Local SQLite file is fine	Persistent data directory and backup plan

Local Development

For the simplest local path, you need:

Docker installed and reachable by the StacyVM process.
Port 7423 available on localhost.
curl for API smoke checks.
Python 3.9+ if you want to use the Python SDK or examples.
Node.js 18+ if you want to use the TypeScript SDK or examples.
Go if you want to run make serve, go test ./..., or build from source.

If you do not have Go installed, use a release binary or Docker Compose instead of make serve. The lowest-friction local setup path is:

npx stacyvm-setup@latest

The npm setup command can clone StacyVM, run npm install for the web, SDK, and TypeScript example packages, download Go modules, build the StacyVM binary, and start the server. It still expects Docker and Go to be installed on the host. Once the repository is already cloned, the source-checkout setup path is:

make dev

make dev checks Go, Docker, Docker daemon access, and port 7423, then builds StacyVM and starts ./stacyvm serve. It does not install Docker Desktop or OS packages for you; when something is missing, it prints the right OS-specific fix. To test the current GitHub source directly without waiting for the npm package, use:

npx github:StacyOS/stacyvm stacyvm-setup

OS Setup

Choose the setup path for the machine where you will run StacyVM.

macOS

macOS is a good local development environment for the Docker provider, SDKs, and docs. Use Docker Desktop as the runtime. Firecracker is not a macOS starter path because it requires Linux/KVM. Install tools:

brew install go git curl make

Install and start Docker Desktop, then verify Docker works:

docker version
docker run --rm hello-world

Run StacyVM from source:

git clone https://github.com/StacyOS/stacyvm.git
cd stacyvm
make dev

Check the API:

curl http://localhost:7423/api/v1/live

Use multi-architecture images such as python:3.12, node:20, or alpine:latest on Apple Silicon.

Windows

Use Windows with WSL 2. Run StacyVM commands inside Ubuntu on WSL, not in PowerShell, so paths, shell behavior, and Docker integration match Linux more closely. Install:

WSL 2 with Ubuntu.
Docker Desktop with WSL integration enabled for your Ubuntu distro.
Go, Git, curl, and make inside Ubuntu.

Inside Ubuntu on WSL:

sudo apt update
sudo apt install -y git curl make golang-go
docker version
docker run --rm hello-world

Run StacyVM:

git clone https://github.com/StacyOS/stacyvm.git
cd stacyvm
make dev

If Docker commands fail inside WSL, open Docker Desktop settings and enable WSL integration for the Ubuntu distro you are using.

Linux

Linux is the recommended host family for runtime work and production certification. Docker is the easiest first provider; Firecracker and PRoot require additional host-specific setup. Install basic tools with your distribution package manager:

sudo apt update
sudo apt install -y git curl make golang-go docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Log out and back in after adding your user to the Docker group, then verify:

docker run --rm hello-world

Run StacyVM:

git clone https://github.com/StacyOS/stacyvm.git
cd stacyvm
make dev

Ubuntu

Ubuntu is the most straightforward Linux path for individual setup and single-node staging. Install Docker and build tools:

sudo apt update
sudo apt install -y ca-certificates curl git make golang-go
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc >/dev/null
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker "$USER"

Log out and back in, then verify:

docker run --rm hello-world
docker compose version

Run StacyVM:

git clone https://github.com/StacyOS/stacyvm.git
cd stacyvm
make dev

For production-like Ubuntu hosts, continue with Production Deployment after local verification.

Runtime Requirements

Docker

Docker is the recommended first runtime because it is easiest to install and validate.

Docker daemon running on the host.
Permission for the StacyVM process to create and destroy containers.
Resource limits configured for memory, CPU, TTL, and concurrent sandboxes.
Production config that disables unsafe Docker options.

Firecracker

Use Firecracker only after host certification.

Linux host with KVM access.
Firecracker binary installed.
Kernel, rootfs, and StacyVM agent configured.
Networking configured for your deployment model.
Runtime certification evidence for the exact host class.

PRoot

Use PRoot only after validating the real rootfs and binaries on the target host.

PRoot installed.
Rootfs path configured.
Required shell and runtime binaries available inside the rootfs.
File and exec conformance passing for your target workload.

Production Requirements

Before exposing StacyVM to other users, prepare:

auth.enabled: true with a strong API key.
Separate admin API key for admin routes.
Exact server.cors_allowed_origins; do not use wildcard CORS for public browser clients.
Rate limits, sandbox caps, TTLs, and quotas.
Persistent store path with backups.
Health checks for /api/v1/live, /api/v1/ready, and /api/v1/health.
Metrics scraping for /api/v1/metrics/prometheus.
Audit log retention policy.
Runtime certification for every provider you publicly claim.

Verify Your Setup

Verify The Npm Bootstrapper

Run this flow in a fresh terminal when you want to confirm the published stacyvm-setup package, clone path, build path, server, and sandbox execution are all working. Verify the npm package:

npm view stacyvm-setup name version bin --json
npx stacyvm-setup@latest --help

Run setup without starting the server:

mkdir -p /tmp/stacyvm-npx-test
cd /tmp/stacyvm-npx-test

npx stacyvm-setup@latest \
  --dir ./stacyvm \
  --no-start

Expected result:

./stacyvm/stacyvm

Start StacyVM:

cd /tmp/stacyvm-npx-test/stacyvm
./stacyvm serve

In a second terminal, check health:

curl http://localhost:7423/api/v1/live
curl http://localhost:7423/api/v1/ready

Create a sandbox:

curl -sS -X POST http://localhost:7423/api/v1/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"image":"python:3.12","ttl":"10m"}'

Copy the returned sandbox ID, then run code inside it:

export SANDBOX_ID="PASTE_ID_HERE"

curl -sS -X POST "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}/exec" \
  -H "Content-Type: application/json" \
  -d '{"command":"python3 -c \"print(40 + 2)\"","timeout":"10s"}'

The response should include:

{
  "stdout": "42\n"
}

Destroy the sandbox:

curl -sS -X DELETE "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}"

After that passes, you can test the full one-command path:

cd /tmp
npx stacyvm-setup@latest \
  --dir ./stacyvm-full-test

Troubleshooting

npm returns 404 for stacyvm-setup

Make sure you are using the published package name:

npm view stacyvm-setup name version bin --json
npx stacyvm-setup@latest --help

If you are testing an unpublished branch, use the GitHub fallback:

npx github:StacyOS/stacyvm stacyvm-setup

Docker CLI is installed, but the daemon is not reachable

On macOS, start Docker Desktop and wait until it is fully running:

open -a Docker
docker info
docker run --rm hello-world

On Windows, run setup inside WSL 2 Ubuntu and enable Docker Desktop WSL integration for that distro.On Linux, start Docker and make sure your user can access it:

sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

Log out and back in after changing groups.

Go is missing

Source setup requires Go because the npm bootstrapper builds the StacyVM binary.macOS:

brew install go

Ubuntu or Debian:

sudo apt update
sudo apt install -y golang-go

Port 7423 is already in use

Stop the process using port 7423, then rerun setup.macOS or Linux:

lsof -iTCP:7423 -sTCP:LISTEN

If you already have StacyVM running, use the existing server and continue with the quickstart.

Setup cloned the repo but failed later

Reuse the existing checkout after fixing the host issue:

cd /tmp/stacyvm-npx-test
npx stacyvm-setup@latest \
  --dir ./stacyvm \
  --no-start

The setup command detects an existing StacyVM checkout and continues from there.

You want to test without Docker temporarily

You can skip Docker daemon validation:

npx stacyvm-setup@latest \
  --skip-docker-check \
  --no-start

This only verifies setup and build behavior. Docker must be running before you create real sandboxes with the Docker provider.

npm cache or auth errors

Use a clean npm cache directory:

npm_config_cache=/tmp/stacyvm-npm-cache npx stacyvm-setup@latest --help

If npm asks for auth unexpectedly, verify your registry:

npm config get registry

It should usually be https://registry.npmjs.org/.

Run config lint before production:

stacyvm config lint --production --file deploy/stacyvm.production.yaml

Run host diagnostics after installation:

stacyvm doctor --production

Run a smoke check against the deployed API:

STACYVM_SMOKE_URL=https://stacyvm.example.com \
STACYVM_API_KEY=sk_live_REPLACE_ME \
scripts/smoke-deployment.sh

Continue

Install StacyVM with the installation guide.
Create your first sandbox with the quickstart.
Review public runtime claims in the support matrix.

Get Started

Build With StacyVM

Operate

Production Readiness

Runtime And Conformance

Architecture

Release Notes

Quick Checklist

Local Development

OS Setup

macOS

Windows

Linux

Ubuntu

Runtime Requirements

Docker

Firecracker

PRoot

Production Requirements

Verify Your Setup

Verify The Npm Bootstrapper

Troubleshooting

Continue

​Quick Checklist

​Local Development

​OS Setup

​macOS

​Windows

​Linux

​Ubuntu

​Runtime Requirements

​Docker

​Firecracker

​PRoot

​Production Requirements

​Verify Your Setup

​Verify The Npm Bootstrapper

​Troubleshooting

​Continue

Quick Checklist

Local Development

OS Setup

macOS

Windows

Linux

Ubuntu

Runtime Requirements

Docker

Firecracker

PRoot

Production Requirements

Verify Your Setup

Verify The Npm Bootstrapper

Troubleshooting

Continue