Skip to main content
smolvm server start runs a local HTTP API that can create sandboxes, list them, delete them, and run commands inside them. Use it when another process needs to control SmolVM without importing the Python SDK.

​
Install dependencies

The server uses the same web dependencies as the dashboard: 
pip install "smolvm[dashboard]"

​
Synopsis

smolvm server start [OPTIONS]

​
Options

​
--host
string
default:"127.0.0.1"
Address to bind.
​
--port
integer
default:"8000"
Port to bind. Must be between 1 and 65535.

​
Start the server

smolvm server start --host 127.0.0.1 --port 8000
The command prints the API URL and OpenAPI spec URL: 
SmolVM HTTP API listening on http://127.0.0.1:8000
OpenAPI spec: http://127.0.0.1:8000/openapi.json

​
Available endpoints

MethodPathWhat it does
POST/sandboxesCreate and start a sandbox
GET/sandboxesList sandboxes on the host
GET/sandboxes/{id}Get one sandbox’s state
POST/sandboxes/{id}/execRun a command inside a sandbox
DELETE/sandboxes/{id}Delete a sandbox

​
Try it with curl

These examples use jq to read the sandbox ID from the JSON response. 
curl -s http://127.0.0.1:8000/sandboxes
Create a sandbox and save the generated ID: 
sandbox_id="$(
  curl -s -X POST http://127.0.0.1:8000/sandboxes \
    -H "Content-Type: application/json" \
    -d '{"os":"ubuntu","memory":512}' \
    | jq -r '.id'
)"

echo "$sandbox_id"
Run a command in that sandbox: 
curl -s -X POST "http://127.0.0.1:8000/sandboxes/${sandbox_id}/exec" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a","timeout":30,"shell":"login"}'
Last modified on June 24, 2026