Skip to main content
This guide gets you from a running StacyVM server to a verified sandbox workflow.

​
Prerequisites

  • A StacyVM server listening on http://localhost:7423.
  • Docker installed and available to the StacyVM process when using the default Docker provider.
  • An API key if auth.enabled is set in your config.
  • Python 3.9+ or Node.js 18+ if you want to use an SDK.
If you have not set up a host yet, start with Developer Onboarding. From a source checkout, the simplest local start command is: 
make dev
From npm/npx, use one command: 
npx stacyvm-setup@latest

​
1. Check The Server

curl -sS http://localhost:7423/api/v1/live
A healthy local server returns a success response. If auth is enabled, send your API key on protected routes: 
export STACYVM_API_KEY="sk_test_YOUR_API_KEY"

​
2. Create A Sandbox

curl -sS -X POST http://localhost:7423/api/v1/sandboxes \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${STACYVM_API_KEY}" \
  -d '{"image":"python:3.12","ttl":"10m","memory_mb":512,"vcpus":1}'
Save the returned sandbox ID: 
export SANDBOX_ID="sb_YOUR_SANDBOX_ID"

​
3. Run Code

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

​
4. Move A File Into The Sandbox

curl -sS -X PUT "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}/files/app/main.py" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ${STACYVM_API_KEY}" \
  -d '{"content":"name = \"StacyVM\"\\nprint(f\"hello from {name}\")\\n","mode":"644"}'

​
5. Destroy The Sandbox

Always destroy sandboxes when work is complete. TTL cleanup is a fallback, not the primary lifecycle control. 
curl -sS -X DELETE "http://localhost:7423/api/v1/sandboxes/${SANDBOX_ID}" \
  -H "X-API-Key: ${STACYVM_API_KEY}"

​
Next Steps