Local API
Drives smolvm programmatically over its local HTTP API (smolvm serve) instead of the...
Install
npx skills add smol-machines/smolvm --skill local-api -g -a claude-code -y- Repository
- smol-machines/smolvm6.9k
- Category
- AI and agents
- Updated
- 3d ago
- License
- Apache-2.0
- Context cost
- Mediumabout 3,000 tokens
- Runs scripts
- Yes, review before use
What it does
Drives smolvm programmatically over its local HTTP API (smolvm serve) instead of the CLI: create machines, exec and stream commands, move files in and out, and tear them down. Use when building a client, harness, agent tool or MCP backend over smolvm; when a create call is accepted but the machine behaves as if a field was ignored; when a file uploaded over the API has disappeared; when an exec that failed still returned HTTP 200; or when choosing between the Unix socket and loopback TCP. Do not use it as a substitute for the CLI in a shell script, and do not bind a plain listener beyond loopback: a server started without mutual TLS has no authentication of any kind.
Driving smolvm over HTTP
Verified on smolvm v1.29.0 on macOS arm64, 2026-10-15, and on v1.18.2 on Linux aarch64, 2026-09-24. Done means a machine went through
its whole lifecycle over HTTP and GET /api/v1/machines/<name> answers NOT_FOUND at the end.
The Linux runs used the scripts of their date; this version's preflight and cleanup scripts ran
on Linux aarch64 on v1.22.2 on 2026-10-03.
Two rules run through everything here, and both are the same shape: a 200 is not a result.
- A failing guest command still returns HTTP 200. Assert
exitCodefrom the body. - Upload files only after the workload container is running. An upload before that returns 200 with the resolved path and byte count for a file that is then unreadable.
Procedure
1. Preflight.
scripts/preflight.sh
It reports auth=none_unless_mtls, which is not a warning about your setup: a server started the
way this packet starts it has no TLS, token or auth of any kind, so the transport you pick is the
access control. Mutual TLS exists, configured from the environment rather than by a flag;
references/traps.md has what it does and the plain listener it opens beside itself.
2. Start the server. A Unix socket is the default here, as it is smolvm's.
scripts/serve-start.sh
scripts/serve-start.sh --listen 127.0.0.1:8899
It waits for "status":"ok" from /health rather than for the process to exist, records the
listen address and pid for cleanup, and reports any Reclaimed N dangling VM data dir(es) line so
you do not later read those directories as a leak. Run again while the recorded server is up, it
prints result=already_serving with the recorded address and starts nothing, whatever --listen
says.
3. Export the spec before writing a request body. This is the step that saves the most time.
smolvm serve openapi -o ./openapi.json
