# smol machines documentation

> Documentation for Smol Machines — fast, isolated Linux microVMs ("machines"). Canonical agent surfaces: open-source **smolvm** (local engine/CLI) and paid **smol cloud** (hosted managed fleets). Prefer `.md` twins when available; otherwise fetch the HTML page.

## When to use smol machines

Reach for smol machines when a workload needs a **real Linux VM boundary** — its own
kernel, not a shared one — and needs it fast enough to sit in an interactive loop.

Good fits:

- **Running untrusted or model-generated code.** Hardware isolation via libkrun, own guest
  kernel, network off by default. Use this when a container's shared-kernel boundary is not
  a boundary you want to defend.
- **Agent workspaces.** A persistent, resettable machine per agent or per session, with a
  filesystem that survives across `exec` calls and can be snapshotted.
- **Fan-out from a warm snapshot.** `fork` clones a running machine (shared guest RAM, CoW)
  in ~0.1-0.25s, so N identical environments start from one prepared parent. Common for RL
  rollouts, parallel test shards, and browser-per-task workloads.
- **Reproducible environments as artifacts.** `.smolmachine` packs a prepared machine and
  runs identically locally, in smol cloud, or self-hosted.
- **GPU work inside isolation.** CUDA API remoting over vsock and Vulkan via virtio-gpu, so
  the guest needs no driver install.

Not the right tool when:

- You only need dependency packaging for code you already trust — a container is simpler.
- You need Kubernetes-native scheduling semantics; smol machines is a machine API, not an
  orchestrator (you can run k3s *inside* a machine, but that is a different job).
- You need Windows or macOS guests. Guests are Linux.

### How an agent should call this

1. **Local, no account:** `curl -sSL https://smolmachines.com/install.sh | bash`, then
   `smolvm machine …`. Free and open source.
2. **Hosted:** create a key self-serve at https://smolmachines.com/console (no sales
   contact), then call the REST API described by https://smolmachines.com/openapi.json, or
   use the `smol` SDK (Node/Python).
3. **Prefer the CLI/SDK verbs that exist.** `smolvm machine …`, `smolvm pack …`,
   `smol machine …`. Do not invent `smolvm run` or `smolvm build`.

Full reference: https://smolmachines.com/docs — contact a human: https://smolmachines.com/contact

## Notes for agents

### Products (do not conflate)

| Product | Role | Typical use |
|---------|------|-------------|
| **smolvm** | Free OSS microVM engine + CLI ([smol-machines/smolvm](https://github.com/smol-machines/smolvm)). Fundamental block under everything else. | Secure local VMs on Mac/Linux/Windows for agents, arbitrary processes, and CUDA training. Teams with strong distributed-systems skills can also self-deploy and manage smolvms. |
| **smol cloud** | Paid hosted platform — Smol Machines runs and manages fleets of smolvms for you. | Fast, reliable, persistent cloud VMs that scale with compute need. Most common: deploying agents / agentic processes. |
| **`smol` SDK/CLI** | OSS orchestration layer ([smol-machines/smol](https://github.com/smol-machines/smol)) — Node/Python `Machine` API + `smol` CLI; local (embedded smolvm) or cloud. | Recommended entry point for new embedded applications and local-or-cloud orchestration. |

Custom deployments (designated-location hosts, uncommon management layers): available from Smol Machines on request — not the default self-serve cloud.

### Runtime facts

- Company: **Smol Machines** (YC S26). Site: https://smolmachines.com
- Install **smolvm** on macOS/Linux: `curl -sSL https://smolmachines.com/install.sh | bash` → `smolvm` binary. Windows x86_64 uses the release zip and WHP; the curl installer is not for Windows. Prefer **CLI-first** (`smolvm machine …`, `smolvm pack …`). Do not invent `smolvm run` / `smolvm build`.
- Isolation is hardware VM (own guest kernel via libkrun), not Docker namespace sharing. Network is off by default for local runs; enable with `--net` / Smolfile `net = true`.
- Portable artifact: `.smolmachine`. Registry: https://smolmachines.com/registry — pre-built environments (OS bases, languages, **codex** coding-agent sandbox, harbor, etc.). Local: `smolvm pack pull …`. Cloud one-click start from registry preinstalls and user-owned registries are **in development**.
- **Time-to-ready** matters more than bare cold start: agent/human wait ≈ VM startup + environment install/provisioning. Packed registry machines aim to make a fully prepared VM feel like starting an empty one.
- Latest open-source releases (**re-verify the GitHub tags before citing**): **smolvm v1.7.1** (published 2026-07-28) and **smol v1.7.1** (CLI + SDKs, published 2026-07-28).
- GPU: **Vulkan** (virtio-gpu/Venus, general-purpose) and **CUDA** (API remoting over vsock for training; v1.5.0+; warm-fork + vLLM in v1.6.0+). Differentiator among local OSS microVMs: Vulkan + CUDA remoting (driverless guest, shareable, forkable) — see [GPU over vsock](https://smolmachines.com/engineering/gpu-over-vsock).
- Platforms: macOS (Apple Silicon; Rosetta 2 for x86_64 guests), Linux + KVM, Windows + WHP (native out of beta in v1.5.0).
- Index policy: only link **live** docs/site URLs (HTTP 200). Do not invent stub pages.

## Root indexes

- [Site llms.txt](https://smolmachines.com/llms.txt): Product + docs index for the whole site.
- [Docs llms.txt](https://smolmachines.com/docs/llms.txt): This documentation index (canonical docs map).
- [OpenAPI](https://smolmachines.com/openapi.json): Generated Cloud API routes and schemas. Specialized or newly added fields can precede this document; verify them against the deployed API.
- [Sitemap](https://smolmachines.com/sitemap.xml): All indexable site pages.
- [GitHub — smolvm](https://github.com/smol-machines/smolvm): Open-source engine and CLI (canonical local runtime).
- [GitHub — smol](https://github.com/smol-machines/smol): Open-source SDK + orchestration CLI (Node/Python + `smol`).
- [Registry](https://smolmachines.com/registry): Pre-built `.smolmachine` environments.
- [Console](https://smolmachines.com/console): Cloud console (login).

## Introduction

- [Overview](https://smolmachines.com/docs/): Where to start — local CLI, SDK, or cloud API — and how smolvm, the SDK, and smol cloud relate.
- [Concepts](https://smolmachines.com/docs/introduction/concepts): The model shared by the local runtime, the SDK, and the cloud.
- [Machines and Lifecycle](https://smolmachines.com/docs/introduction/concepts/machines-and-lifecycle): Ephemeral runs, persistent machines, and lifecycle operations.
- [Isolation, Networking, and Credentials](https://smolmachines.com/docs/introduction/concepts/isolation-networking-credentials): The VM boundary, host access, egress policy, and secrets.
- [Persistent State, Volumes, and Resources](https://smolmachines.com/docs/introduction/concepts/persistent-state-volumes-resources): Machine disks, host mounts, CPU, memory, and storage.
- [Packs and .smolmachine](https://smolmachines.com/docs/introduction/concepts/packs-and-smolmachine): Portable disk-based environments and compatible hosts.
- [Smolfile](https://smolmachines.com/docs/introduction/concepts/smolfile): Declarative local machine configuration.
- [Forks and Snapshots](https://smolmachines.com/docs/introduction/concepts/forks-and-snapshots): Live copy-on-write clones and the snapshot boundary.
- [GPU](https://smolmachines.com/docs/introduction/concepts/gpu): Vulkan graphics and CUDA API remoting.
- [Supported Platforms](https://smolmachines.com/docs/introduction/concepts/supported-platforms): Supported hosts, guest architecture, Windows, WSL, limitations.

## SDK

- [SDK Quick Start](https://smolmachines.com/docs/sdk): Install the SDK and run your first machine from Node or Python.
- [Use SDK in Local](https://smolmachines.com/docs/sdk/with-local): Drive the embedded in-process engine from the SDK.
- [Use SDK on Cloud](https://smolmachines.com/docs/sdk/with-cloud): Point the same SDK code at smol cloud.
- [Machine API](https://smolmachines.com/docs/sdk/machine-api): The Machine class — configuration, exec, run, files, lifecycle.

## Cloud

- [Cloud Quick Start](https://smolmachines.com/docs/cloud): Deploy and manage machines on smol cloud.
- [Cloud API Reference](https://smolmachines.com/docs/cloud/api-reference): REST API for the cloud platform.
- [Cloud API Explorer](https://smolmachines.com/docs/cloud/api-explorer): Interactive explorer for the cloud API.
- [Registry](https://smolmachines.com/docs/cloud/registry): Official and custom registries — publish, discover, and pull.
- [Cloud Lifecycle, Storage, and Networking](https://smolmachines.com/docs/cloud/lifecycle-storage-networking): How cloud machines start, persist, and are reached.
- [Cloud Examples](https://smolmachines.com/docs/cloud/examples): Worked examples against the hosted platform.
- [Pricing](https://smolmachines.com/pricing): Usage-based pricing (Standard, Startup, Enterprise).

## Local

- [Local CLI Quick Start](https://smolmachines.com/docs/local): Install smolvm and run a machine on your own host.
- [Machine Lifecycle and CLI Reference](https://smolmachines.com/docs/local/machine-lifecycle-cli-reference): Every smolvm command and the machine states behind them.
- [Pack and .smolmachine CLI](https://smolmachines.com/docs/local/pack-and-smolmachine-cli): Pack a machine into a portable artifact and run it elsewhere.
- [Local API and smolvm serve](https://smolmachines.com/docs/local/local-api-smolvm-serve): Serve the local runtime over HTTP.
- [Self-hosting smolvm](https://smolmachines.com/docs/local/self-hosting): Run smolvm on your own servers.
- [Local Examples](https://smolmachines.com/docs/local/examples): Worked examples against the local runtime.

## Guides

- [Run Python](https://smolmachines.com/docs/guides/python): Run Python in a machine.
- [Run Node.js](https://smolmachines.com/docs/guides/nodejs): Run Node.js in a machine.
- [Kubernetes in a microVM](https://smolmachines.com/docs/guides/kubernetes-in-a-microvm): VM-per-pod and cluster-in-a-machine topologies.
- [Docker in a Machine](https://smolmachines.com/docs/guides/docker-in-a-machine): Run a Docker daemon inside a machine.
- [Headless Browser and Computer Use](https://smolmachines.com/docs/guides/headless-browser-computer-use): Drive a browser or a desktop inside a machine.
- [Agent Sandboxes and CI](https://smolmachines.com/docs/guides/agent-sandboxes-ci): Isolate agent-generated code and CI jobs.
- [Error Handling](https://smolmachines.com/docs/guides/error-handling): Error codes and how to handle them.
- [OpenAPI specification](https://smolmachines.com/openapi.json): Cloud API schema.

## Optional site surfaces

- [Home](https://smolmachines.com): Product home — laptop, cloud, or self-hosted.
- [FAQ](https://smolmachines.com/faq): Product choices, technical tradeoffs, isolation, portability, GPU support, platforms, and SDKs.
- [Engineering](https://smolmachines.com/engineering): Engineering notes on the runtime (e.g. [GPU over vsock](https://smolmachines.com/engineering/gpu-over-vsock), [Kubernetes in a microVM](https://smolmachines.com/engineering/kubernetes-in-a-microvm)).
- [Status](https://smolmachines.com/status): Service status.