Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stacyide.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This is the fastest path for a developer who wants StacyVM running locally.

​
Start StacyVM

Run this in a fresh terminal: 
npx stacyvm-setup@latest
The setup command clones StacyVM if needed, installs package dependencies, downloads Go modules, builds the binary, and starts the server at http://localhost:7423.
You still need Docker Desktop or Docker Engine running locally. If Docker is not reachable, setup stops and prints the fix for your operating system.

​
Clean Verification Flow

Use this flow when you want to verify each step before starting the server.

​
1. Verify The Npm Package

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

​
2. Run Setup Without Starting The Server

This checks clone, dependency installation, Go module download, and build behavior safely. 
mkdir -p /tmp/stacyvm-npx-test
cd /tmp/stacyvm-npx-test

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

​
3. Start StacyVM

cd /tmp/stacyvm-npx-test/stacyvm
./stacyvm serve
Leave this terminal running.

​
4. Check Health

In a second terminal: 
curl http://localhost:7423/api/v1/live
curl http://localhost:7423/api/v1/ready

​
5. 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.

​
6. Run Code

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"}'
Expected output includes: 
"stdout": "42\n"

​
7. Destroy The Sandbox

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

​
8. Optional Full One-Command Run

After the verification flow passes: 
cd /tmp
npx stacyvm-setup@latest --dir ./stacyvm-full-test
This sets up StacyVM and starts the server directly.

​
Common Fixes

Start Docker, then verify it:
docker info
docker run --rm hello-world
On macOS, start Docker Desktop:
open -a Docker
On Windows, run setup inside WSL 2 Ubuntu and enable Docker Desktop WSL integration for that distro.
Install Go, then rerun setup.macOS:
brew install go
Ubuntu or Debian:
sudo apt update
sudo apt install -y golang-go
Check what is listening:
lsof -iTCP:7423 -sTCP:LISTEN
Stop that process, or use the StacyVM server that is already running.
Skip server startup:
npx stacyvm-setup@latest --dir ./stacyvm --no-start
If Docker is not running yet, you can also skip Docker validation:
npx stacyvm-setup@latest --dir ./stacyvm --no-start --skip-docker-check

​
Next Steps