Smol Machines

Run ANY smolvm subcommand in a fast, hardware-isolated Linux microVM LOCALLY. Payload is {"args":[...]} (verbatim smolvm argv) with optional {"stdin":"..."}. This one method exposes the whole smolvm CLI — for the complete agent reference call smol.exec {"args":["--help"]}, and for any subcommand call smol.exec {"args":["<group>","--help"]}. COMMAND SURFACE: • machine run — create an EPHEMERAL VM, run one command, tear down (nothing persists). e.g. ["machine","run","--net","--image","alpine","--","sh","-c","echo hi"]. • machine create | start | stop | delete — lifecycle of a PERSISTENT named VM (--name, default "default"). • machine exec — run a command in a persistent VM; FILESYSTEM CHANGES PERSIST across sessions (package installs stick). e.g. ["machine","exec","--name","myvm","--","apk","add","python3"]. • machine status | ls | images | monitor — read-only introspection (do NOT stop a running VM). • machine cp — copy files host↔VM (HOST:GUEST). machine update — change mounts/ports/env/cpu/memory on a STOPPED VM. machine prune — reclaim layers (prune --all needs the VM stopped). • pack create -o <out> — build a portable, self-contained .smolmachine executable; pack run — run one. machine create --from <artifact>.smolmachine for fast start. • serve start --listen <addr> — HTTP API server (POST/GET /api/v1/machines…); serve openapi — the spec. • config — manage registries + defaults. KEY FLAGS: --net (networking is OFF by default), --image <oci ref | ./archive.tar | ./rootfs/ | ->, -v HOST:GUEST[:ro] (mount; -v host:/workspace replaces the default workspace), -p HOST:GUEST (port), --gpu, --ssh-agent (forward host SSH agent; keys never enter the VM), --secret-env GUEST=HOST / --secret-file GUEST=/abs / -s Smolfile (inject secrets by reference), --from <artifact>, --cpus, --memory. DEFAULTS: network off; cpus 4; memory 8192 MiB; storage 20 GiB; name "default". Elastic memory/CPU via virtio balloon. NOT SUPPORTED OVER IPC: interactive sessions (-it / machine shell) and long-running serve (no attached TTY).

Report the local smolvm engine version. This is `smolvm --version`.

Provision (or fetch) this Pilot user's proprietary smol cloud key and free credit balance. Runs automatically on install and on smol.help — you rarely call it directly. The key is bound to your Pilot identity, stored only in your app's private secrets, and used to push and isolate your cloud VMs. Returns {key, credits}.

Report your remaining smol cloud credit balance. Returns {credits}.

Push a VM to the smol cloud as YOU (your provisioned key) and START it running. Provide either a local packed artifact (base64 of a `smolvm pack` output) OR an OCI `image` reference the cloud pulls; pass {"net":true} for outbound networking (off by default). BILLING: you must have credit to start (402 if empty); the running VM then drains your credit by REAL usage (CPU + memory + disk per the rate card in smol.help) and the broker STOPS it when your credit runs out. The machine is tagged as owned by you, so no other user can see or touch it. Returns the created machine.

List YOUR smol cloud machines (only yours — the broker filters by owner). Free (no credit). Returns an array of machines.

Get your current smol cloud key (the per-user credential bound to your Pilot identity). Idempotent — safe to call anytime. The key is also cached in your app's private secrets. Returns {key, credits}.

Rotate your smol cloud key if it leaked. Your OLD key stops working immediately and a NEW key is issued — your credit and cloud machines are NOT affected (only the key changes). Returns {key, credits, rotated}.

Discovery: every method with params, kind, and latency class.