Use the SmolVM HTTP API and TypeScript SDK

SmolVM can run a local HTTP server so another process can create sandboxes and run commands without importing Python. This is useful for web apps, local tools, TypeScript services, and agent runtimes that already speak HTTP.

When to use the HTTP API

Use the HTTP API when:

A JavaScript or TypeScript process needs to create and control sandboxes.
A local service needs a stable REST interface instead of Python objects.
You want to generate clients from the OpenAPI spec.
You want to keep one SmolVM server process alive while several tools make requests.

For Python-only workflows, the SmolVM class is still the shortest path.

Start the server

Install the web dependencies:

pip install "smolvm[dashboard]"

Start the local server:

smolvm server start --host 127.0.0.1 --port 8000

You should see:

SmolVM HTTP API listening on http://127.0.0.1:8000
OpenAPI spec: http://127.0.0.1:8000/openapi.json

Keep the server bound to 127.0.0.1 unless you have added your own network controls. The local API can create sandboxes and run commands on your machine.

Core endpoints

Method	Path	What it does
`POST`	`/sandboxes`	Create, boot, and register a sandbox
`GET`	`/sandboxes`	List sandboxes on the host
`GET`	`/sandboxes/{id}`	Get one sandbox’s state
`POST`	`/sandboxes/{id}/exec`	Run a command inside a sandbox
`GET`	`/sandboxes/{id}/desktop`	Get the sandbox’s desktop connection details
`DELETE`	`/sandboxes/{id}`	Stop and delete a sandbox

Create a sandbox with curl

curl -s -X POST http://127.0.0.1:8000/sandboxes \
  -H "Content-Type: application/json" \
  -d '{"os":"ubuntu","memory":512,"disk_size":1024}'

Example response:

{
  "id": "vm-a1b2c3d4",
  "status": "running"
}

The request body mirrors the auto-config options of the Python SmolVM(...) constructor.

"alpine" | "ubuntu" | "windows"

Guest operating system. Omit it for the default Linux sandbox.

string

Image reference to boot, such as an S3 image URI, file:// URI, or local Windows qcow2 path.

integer

Guest memory in MiB.

integer

Guest disk size in MiB.

"firecracker" | "qemu" | "libkrun"

Runtime backend override.

Run a command

curl -s -X POST http://127.0.0.1:8000/sandboxes/vm-a1b2c3d4/exec \
  -H "Content-Type: application/json" \
  -d '{"command":"python3 --version","timeout":30,"shell":"login"}'

Example response:

{
  "exit_code": 0,
  "stdout": "Python 3.12.3\n",
  "stderr": ""
}

string

required

Command to run inside the sandbox.

integer

default:"30"

Maximum seconds to wait for the command.

"login" | "raw"

default:"login"

Use login for the guest login shell, or raw to run the command without shell wrapping.

Use the TypeScript client

The SmolVM repository includes a generated TypeScript client and a small wrapper class named Smolvm. In a project where that TypeScript package is available, point it at the local server:

smolvm-client.ts

import { Smolvm } from "smolvm";

const smolvm = new Smolvm({
  baseUrl: "http://127.0.0.1:8000",
});

const sandbox = await smolvm.sandbox.create({
  os: "ubuntu",
  memory: 512,
  disk_size: 1024,
});

const result = await smolvm.sandbox.exec(sandbox.id, {
  command: "uname -a",
  timeout: 30,
  shell: "login",
});

console.log(result.stdout);

await smolvm.sandbox.delete(sandbox.id);

The wrapper groups operations under smolvm.sandbox:

Method	HTTP call
`smolvm.sandbox.create(...)`	`POST /sandboxes`
`smolvm.sandbox.list()`	`GET /sandboxes`
`smolvm.sandbox.get(id)`	`GET /sandboxes/{id}`
`smolvm.sandbox.exec(id, body)`	`POST /sandboxes/{id}/exec`
`smolvm.sandbox.desktop(id)`	`GET /sandboxes/{id}/desktop`
`smolvm.sandbox.delete(id)`	`DELETE /sandboxes/{id}`

Get sandbox desktop connection details

Use sandbox.desktop(id) to get the details you need to open a sandbox’s desktop viewer from a Node or TypeScript app. This is the SDK equivalent of the smolvm sandbox desktop CLI command, so you can wire the same workflow into a service or agent instead of shelling out.

sandbox-desktop.ts

import { Smolvm } from "smolvm";

const smolvm = new Smolvm({
  baseUrl: "http://127.0.0.1:8000",
});

const desktop = await smolvm.sandbox.desktop("vm-a1b2c3d4");

console.log(desktop.protocol);   // "vnc"
console.log(desktop.host);       // "127.0.0.1"
console.log(desktop.port);       // e.g. 5900
console.log(desktop.viewer_url); // URL to open in a desktop viewer

The returned DesktopResponse has:

protocol — the desktop protocol, currently "vnc".
host — the loopback host the desktop is bound to.
port — the port the desktop is listening on.
viewer_url — a URL you can hand to a desktop viewer to open the session.

Point your viewer at viewer_url, or build your own connection from host and port. The method throws if the sandbox has no desktop or the server rejects the request.

The docs intentionally avoid an npm install command here. The release source includes the ts/ package and generated client, but package publication should be verified before documenting a registry install path.

Generate clients from OpenAPI

The server publishes its OpenAPI spec at:

http://127.0.0.1:8000/openapi.json

Use that URL with your client generator of choice when you need another language or a custom TypeScript client.

Troubleshooting

The server says dashboard dependencies are missing

Install the web extra, then start the server again:

pip install "smolvm[dashboard]"
smolvm server start --host 127.0.0.1 --port 8000

The port is already in use

Pick another port:

smolvm server start --port 8001

A command exits non-zero

A command that runs and returns a non-zero exit code still produces a successful HTTP response. Check exit_code, stdout, and stderr in the response body.

smolvm server

CLI reference for the local API server

SmolVM Python API

Use SmolVM directly from Python

Get Started

Features

Guides

Architecture

Operations

Use the SmolVM HTTP API and TypeScript SDK

When to use the HTTP API

Start the server

Core endpoints

Create a sandbox with curl

Run a command

Use the TypeScript client

Get sandbox desktop connection details

Generate clients from OpenAPI

Troubleshooting

smolvm server

SmolVM Python API

​When to use the HTTP API

​Start the server

​Core endpoints

​Create a sandbox with curl

​Run a command

​Use the TypeScript client

​Get sandbox desktop connection details

​Generate clients from OpenAPI

​Troubleshooting

​Related

smolvm server

SmolVM Python API

When to use the HTTP API

Start the server

Core endpoints

Create a sandbox with curl

Run a command

Use the TypeScript client

Get sandbox desktop connection details

Generate clients from OpenAPI

Troubleshooting

Related