Local API and smolvm serve
smolvm serve exposes local machine operations over HTTP. Use it for integrations that need a long-running local REST endpoint or already depend on the older smolvm-sdk client.
For new Node.js and Python applications, use the embedded smolmachines SDK instead. It runs the local engine in-process and can use the same Machine API with smol cloud. It does not require smolvm serve.
Start the local server
Listen on loopback:
smolvm serve start --listen 127.0.0.1:8080 Or listen on a Unix socket:
smolvm serve start --listen "$XDG_RUNTIME_DIR/smolvm.sock" Generate the OpenAPI specification for the installed version:
smolvm serve openapi One server to a host, unless you move a second port
Every smolvm serve also binds a guest ingress port, 127.0.0.1:10081 by default, which --listen does not move. A second server on the same host therefore fails at start whatever address it was
given:
Error: config operation failed: bind guest rollout ingress: 127.0.0.1:10081: Address already in use Give the second server its own port with --guest-rollout-port PORT, or SMOLVM_GUEST_ROLLOUT_HOST_PORT, and the two run side by side. A running machine keeps the port it
started with.
Operator flags
| Flag | What it does |
|---|---|
--cache-disk-dir DIR | Directory of cache disk bases the API may attach, named by file name in cacheDisk on create and never by path. POST /api/v1/machines/:name/cache-disk/publish writes a stopped machine’s cache, base and writes together, into it as a new base under a new name. Unset, the API refuses cache disks |
--cache-disk-max-gb GiB | Most the bases in --cache-disk-dir, which it requires, may hold: past it the least recently used unattached bases are removed and fetched again when needed. Half that directory’s filesystem by default, and a tenth of the filesystem is always kept free |
--allow-nested-virt | Permit machines created with nestedVirt. Off by default, because it exposes the host kernel’s nested virtualization to the guest; turning it off again also stops existing nested machines from starting |
--egress-watchlist PATH | Record guest traffic to destinations named in a file of <label> dns-sha256:<hex> or <label> ip-sha256:<hex> lines, and block it on a line that ends in block: a matching lookup is answered as nonexistent and a matching connection is dropped. Matches come back as egressSignals on the machine, the file is re-read when it changes, and it applies to virtio-net machines. A TLS server name is matched like a DNS name, and a stratum login is recorded as the signal stratum |
--shutdown-grace SECS | Seconds in-flight requests get once the server stops accepting connections, five by default and capped at 3600. Connections are refused for the whole grace, so to restart without cutting off a long exec, wait for GET /inflight on the loopback door to report nothing in flight |
--mtls-client-cn CN | Require this subject CN on the mTLS client certificate. Only applies when serve TLS is configured; unset, every certificate the client CA signed is accepted for every route |
--mtls-allow-peer-blobs | With --mtls-client-cn, also accept other certificates the client CA signed, but only on the peer blob routes under /p2p/, for sibling hosts that fetch cached layers from this one |
--local-image-dir DIR | Directory of local images the API may create machines from: docker save or OCI archives and unpacked rootfs directories. A request’s image path must resolve inside it; unset, the API accepts registry images only |
--restore-cache-entries N | Restored checkpoints kept extracted after their machines are gone, so restoring one again reuses it; 32 by default, 0 keeps none |
--restore-cache-gib GiB | Space those kept checkpoints may hold together, 256 GiB by default |
--prepared-checkpoint-cache-gib GiB | Space for captured checkpoints kept on this host, so restoring one here skips the download; 64 GiB by default, and SMOLVM_PREPARED_CHECKPOINT_CACHE_MAX_BYTES takes precedence when set |
--cors-origin ORIGIN | Allowed CORS origin, repeatable; localhost:8080 and localhost:3000 by default |
--json-logs | Write logs as structured JSON for a log aggregator |
Selected HTTP endpoints
| Method | Path | Operation |
|---|---|---|
POST | /api/v1/machines | Create a machine |
GET | /api/v1/machines | List machines |
GET | /api/v1/machines/:name | Get one machine |
POST | /api/v1/machines/:name/start | Start a machine |
POST | /api/v1/machines/:name/stop | Stop a machine |
POST | /api/v1/machines/:name/pause, /resume | Save a running machine’s execution durably and stop it; resume it under the same name |
POST | /api/v1/machines/:name/resize | Grow a running machine’s CPUs, memory or disks: cpus, memoryMb, storageGb or overlayGb, one kind per request. Asking for two together answers 400 resize CPUs, RAM, and disks in separate requests, although machine resize takes them together. CPUs or memory on a stopped machine answer 400; change those with machine update |
POST | /api/v1/machines/:name/egress | Change the egress allow list, the API form of machine update --allow-host and its siblings, below |
GET | /api/v1/machines/:name/egress-events | Outbound connections and lookups the egress policy refused; ?limit= keeps the newest that many, 200 by default |
POST | /api/v1/machines/:name/sync | Copy a running machine’s staged mounts back to the host without stopping it |
POST | /api/v1/machines/:name/branches | Branch a running source started branchable into a new running child; any other source is refused |
PUT | /api/v1/machines/:name/cpu-limit | Cap the host CPU a running machine’s VMM may use, as {"millicpus": N} across all its vCPUs (200 is a fifth of one CPU), or {"millicpus": null} to clear it; the guest still sees every vCPU, and the limit holds across restarts until cleared. A stopped machine answers 409. It needs the VMM in a cgroup smolvm controls, so the request is refused with 400 on macOS, and on Linux unless serve runs as root on systemd or can write its own cgroup, as in a systemd unit with Delegate=yes. The CLI has no equivalent |
PUT | /api/v1/machines/:name/credential-values | Supply the values for a machine’s credential bindings as {"values": {"<binding>": "<value>"}}, 204; a running machine uses them at once, and a name with no binding answers 400 |
DELETE | /api/v1/machines/:name | Delete a machine |
PUT | /api/v1/machines/:name/ports | Replace a machine’s published ports with the whole set, as {"ports": [{"host": 8080, "guest": 80}]}; an empty list removes them all. TCP changes apply live while it runs; a UDP change on a running machine answers 409, and so does a taken host port, with PORT_IN_USE |
GET, POST, DELETE | /api/v1/machines/:name/mounts | List, add or remove host directories mounted into a running machine; POST takes source, target and readonly, DELETE takes ?target=, and a stopped machine answers 409 |
POST | /api/v1/machines/:name/exec | Execute a command |
POST | /api/v1/machines/:name/exec/stream | Stream execution over SSE |
POST, GET | /api/v1/machines/:name/execs | Start an exec session, or list them |
GET, DELETE | /api/v1/machines/:name/execs/:exec | Read a session’s output after ?after=, or end it |
POST | /api/v1/machines/:name/execs/:exec/stdin, /resize | Send numbered stdin frames, or resize its terminal |
PUT | /api/v1/machines/:name/files/*path | Upload a file: up to 1 GiB with a Content-Length, 100 MiB without, 413 beyond. ?uid=, ?gid= and ?mode= (octal) set its owner and permissions; with no owner it belongs to the workload’s user |
GET | /api/v1/machines/:name/files/*path | Download a file |
GET | /api/v1/machines/:name/logs | Stream logs over SSE |
POST | /api/v1/machines/:name/images/pull | Pull an OCI image |
POST | /api/v1/pools | Create a warm pool of branched workers from a branchable source |
GET, DELETE | /api/v1/pools/:name | Read or delete a pool |
PUT | /api/v1/pools/:name/size | Change how many clean workers a pool keeps ready |
POST | /api/v1/pools/:name/leases | Lease one clean worker |
POST | /api/v1/pools/:name/leases/:lease/heartbeat | Extend a lease |
POST | /api/v1/pools/:name/leases/:lease/complete | Finish a lease; the pool replaces its worker |
POST /egress adds to or takes from the allow list rather than replacing the whole policy:
curl -X POST http://127.0.0.1:8080/api/v1/machines/dev/egress \
-H 'content-type: application/json' -d '{"allowHosts": ["pypi.org"]}' Its body takes allowHosts, allowHostPatterns, allowCidrs, allowUdp, removeAllowHosts, removeAllowCidrs, removeAllowUdp, outboundLocalhostOnly, resetAllowList and allowAll, and refuses any other field with 422. allowAll permits a removal or reset that leaves no entry. A stopped machine takes any change from its next start. A running machine takes, from its next connection or lookup, any change that keeps an allow list in force; one that lifts the list, or gives one to a machine running without one, answers 409 until the machine is stopped. A request that names no change, such as an empty body or allowAll alone, answers 400 request contains no egress changes. A host that machine create --allow-host added also put its resolved addresses in the allowed CIDRs, and removing the host leaves them; take them out with removeAllowCidrs. A host added through this route is kept as a name only. resetAllowList with the entries to keep leaves exactly those, except that on a running machine left with no allowed host, addresses the guest already looked up stay reachable until their DNS TTL expires.
An exec session belongs to the machine rather than the connection that started it, so a client can drop off and read the rest later. Choose its execId, 8 to 64 of A-Z, a-z, 0-9, _ and -, before the first try, and a retried start finds the session the first one made instead of running the command twice. Read output with ?after= set to the last answer’s next until done, then DELETE it. smolvm serve openapi gives the frame format.
A warm pool keeps desiredReady workers branched from a source machine and ready to hand out. The source must be started branchable and its workload must reach its branch point by running under smolvm-branch-ready; until it does, the pool stays provisioning. A lease takes an idempotencyKey: repeating a request with the same key and the same body returns the same lease, and the same key with a different body is refused with 409. A lease expires unless heartbeated, 300 seconds by default, and completing it retires the worker while the pool branches a fresh one.
The HTTP API covers common lifecycle, execution, file, image, volume, export, and branch operations. It does not have complete parity with every CLI command or interactive CLI behavior. Use the generated OpenAPI document as the wire-level reference for your installed release.
A branch request waits for the source up to 60 seconds plus 20 seconds per GiB of its memory, at most 540 seconds, then answers a retryable 503. With "keepMachineId": true the child keeps the source’s /etc/machine-id, for tools that key a cache by it; its hostname is still its own name.
A start takes branchable, branchPoolSize and cudaVramLimitMib in its JSON body or its query string; when both carry one, the query string wins.
A create body is validated strictly: an unknown field is refused with 422 and a message naming
the field and listing the ones it accepts, and so is a known field of the wrong type. A field this
release does not have is refused rather than dropped in silence.
A create body’s diskVolumes lists guest paths kept on the machine’s storage disk instead of its
overlay root, the API form of -v /var/lib/docker. A running machine’s record carries cpuLimitMillicpus while a CPU limit is set and, on a virtio-net machine, egressFlows: its open
TCP flows, how many distinct peers they reach and the oldest one, refreshed about every 15 seconds.
A running machine in the list also carries pressure, the guest’s CPU, memory and IO stall
figures that machine stats prints, sampled about every 15 seconds.
Choose an integration
Recommended: embedded smolmachines SDK
Use npm or PyPI package smolmachines for new Node.js and Python applications.
- The local engine is embedded through native bindings
- No separate server process is required
- The API can target local machines or smol cloud
- This is the current SDK path in the
smolrepository
See SDK Quick Start and Use SDK in Local for installation and code examples.
Legacy REST client: smolvm-sdk
The older smolvm-sdk repository holds npm, Python and Go REST clients for a running smolvm serve process. Its npm and Python packages are named smolvm in source, but the smolvm on npm is an empty placeholder and the smolvm on PyPI is a different project, so neither registry installs these clients.
Use this path when:
- An existing integration already uses the local REST API
- A separate local runtime process is part of the deployment design
- The application language cannot use the embedded Node.js or Python packages
Do not confuse the package names:
| Package | Connection model | Recommended use |
|---|---|---|
smolmachines | Embedded local engine; optional cloud transport | New Node.js and Python applications |
The smolvm-sdk clients, named smolvm in source | HTTP client to smolvm serve | Existing or server-oriented REST integrations |
Security and deployment boundary
Without mutual TLS (SMOLVM_SERVE_TLS_CERT, _KEY, _CLIENT_CA) the local server has no authentication. Bind it to loopback or a protected Unix socket. Do not expose port 8080 to an untrusted network.
If another host or user must reach the API, place it behind an authenticated, encrypted proxy and enforce host-level account isolation. Anyone who can call the API can ask the runtime to create machines and execute workloads with the capabilities granted to the server process.
smolvm serve is a per-host runtime API. It is not the standalone smol cloud fleet control plane.
A machine serve starts cannot reach a private, carrier-NAT or loopback address even when its allowedCidrs names one: serve raises the egress floor for every machine it starts, and no allow list entry lowers it. To lift it, set SMOLVM_EGRESS_FLOOR before starting serve: metadata keeps only the link-local range that holds cloud metadata blocked, and off blocks nothing. Neither is the CLI’s default, which also blocks the host’s loopback.