Skip to content
Get packs

Guide · Agent skill

How to use the Driving smolvm over HTTP agent skill (local-api)

Updated · written with AI from the project's own documentation and checked against our catalogue data

This agent skill teaches an AI agent to control smolvm, a tool for running lightweight virtual machines, through its local HTTP API (smolvm serve) instead of typing CLI commands. It is written for developers building a client, test harness, agent tool or MCP backend on top of smolvm. After working through it you will know how to install the skill, how to phrase requests that trigger it, and which known pitfalls to check for.

Driving smolvm over HTTPsmol-machines/smolvm · Apache-2.0

Quick start

  1. 1Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
  2. 2Confirm requirements. Check that the smolvm CLI, bash, curl and python3 are available on a Unix or Linux/macOS host.
  3. 3Run preflight. Run scripts/preflight.sh and read the auth=none_unless_mtls line before exposing anything.
  4. 4Start the server. Run scripts/serve-start.sh for a Unix socket, or add --listen 127.0.0.1:8899 for loopback TCP.
  5. 5Export the spec. Run smolvm serve openapi -o ./openapi.json and use its field names in request bodies.
  6. 6Run the lifecycle check. Run scripts/lifecycle-check.sh and confirm it ends with result=lifecycle_ok.
  7. 7Clean up. Run scripts/cleanup.sh --purge to delete recorded machines and stop the server.

What the skill makes the agent do

Normally you would control smolvm by typing commands in a terminal. With this skill installed, the agent talks to smolvm's local HTTP API instead. It can create a machine, start it, run commands inside it, stream output, copy files in and out, and delete it.

The skill also ships shell scripts that check each step and clean up afterwards, and it warns about known pitfalls such as uploads that silently disappear and failed commands that still return HTTP 200.

How to install the local-api skill

Download the ZIP for this skill from this page. You can install it in either of two ways: unzip it into ~/.claude/skills/ for personal use, or unzip it into a project's .claude/skills/ folder to share it with that project. Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The package contains SKILL.md, a README.md, three reference files (references/api-fields.md, references/traps.md, references/windows.md) and four scripts in scripts/ (preflight.sh, serve-start.sh, lifecycle-check.sh and cleanup.sh).

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What you need before it runs

The skill expects the smolvm CLI to be installed; it was verified on v1.29.0 and v1.18.2. The provided scripts also need bash, curl and python3. It is meant for a Unix or Linux/macOS host able to run smolvm.

The scripts run commands and the skill uses the network, so review them before first use.

  • smolvm CLI installed
  • bash, curl and python3 available for the scripts
  • A Unix or Linux/macOS host able to run smolvm

Run the server and check the setup

Start by running the preflight script. It reports auth=none_unless_mtls, which is a property of the server, not a warning about your setup: a server started this way has no TLS, token or auth of any kind, so the transport you choose is the access control. Then start the server. A Unix socket is the default; you can request loopback TCP instead.

The start script waits for a healthy response from /health before reporting success, and records the listen address and pid for cleanup. If a server is already running, it reports that and starts nothing.

scripts/preflight.sh scripts/serve-start.sh scripts/serve-start.sh --listen 127.0.0.1:8899

Export the API spec before writing requests

Before writing a request body, export the spec from your own binary. The field names in the API are the schema's, not the CLI's flags: network rather than net, memoryMb rather than memory, and cmd for the workload. From v1.22.2 an unknown field is refused with 422 and a message that names it; earlier releases accepted it with 200 and ignored it.

The skill's references/api-fields.md lists the full field names.

smolvm serve openapi -o ./openapi.json

Run the lifecycle check

The lifecycle script creates a machine, starts it, waits for the workload to answer, runs a normal exec and a deliberately failing exec, streams output, round-trips a file, stops and deletes the machine, then asserts the machine is gone. A passing run ends with result=lifecycle_ok.

scripts/lifecycle-check.sh

Clean up machines first

Run the cleanup script when you are done. It waits up to 20 seconds for ephemeral machine entries to retire. Order matters: stopping the server does not stop machines, which keep running after it exits. The script deletes recorded machines, then stops the server, then removes the socket.

scripts/cleanup.sh --purge

What people use it for

  • Building a client library that creates, execs in and deletes smolvm machines
  • Writing a test harness that gives each test run a fresh sandboxed machine
  • Backing an MCP server or agent tool with sandboxed machine execution
  • Checking that an exec's non-zero exitCode is asserted from the response body rather than the HTTP status

Frequently asked questions

How do I install the local-api agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need installed to use this skill?

You need the smolvm CLI (verified on v1.29.0 and v1.18.2), plus bash, curl and python3 for the provided scripts. It is meant for a Unix or Linux/macOS host able to run smolvm.

Is the smolvm HTTP API secure by default?

No. The skill states that a server started without mutual TLS has no authentication of any kind, so anyone who can reach the socket or port can create and run machines. Keep it on a Unix socket or loopback address and do not bind a plain listener beyond loopback.

Why does my failed command still return HTTP 200?

The skill notes that a failing guest command still returns HTTP 200. Check the exitCode field in the response body instead of relying on the HTTP status.

Why did my uploaded file disappear?

The skill warns that uploads made before the workload container is running can return 200 yet be unreadable afterwards, because paths such as /tmp are mounted over by the container. Upload only after a successful exec.

Should I use this skill instead of the smolvm CLI in a shell script?

No. The skill says not to use it as a substitute for the CLI in a shell script. For simple one-off shell automation, the smolvm CLI is the better fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are building a client, test harness, agent tool or MCP backend on top of smolvm and need to manage machine lifecycles through its HTTP API. Pick the smolvm CLI for simple shell automation, and avoid exposing the plain server on any network address without mutual TLS.

Download the skill