# smol machines documentation

> Documentation for smol machines — use the `smol` / `smolmachines` SDK and orchestration CLI for new local-or-cloud applications, `smolvm` for the open-source local runtime CLI, or smol cloud for hosted infrastructure. Each page below is served as HTML at its URL.

Start with the [agent quickstart](https://smolmachines.com/docs/guides/agent-quickstart) for a complete local branching and checkpoint workflow. Each page is also served as Markdown: append `.md` to its URL (the overview is https://smolmachines.com/docs/index.md), or request it with `Accept: text/markdown`.

## introduction

- [Agent quickstart](https://smolmachines.com/docs/guides/agent-quickstart): Install locally, prepare a machine, verify four independent branches, checkpoint, restore, and clean up.
- [Overview](https://smolmachines.com/docs/): What Smol Machines is, 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, explicit host access, egress policy, and secret handling.
- [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.
- [Branches and Checkpoints](https://smolmachines.com/docs/introduction/concepts/forks-and-snapshots): Live copy-on-write clones, packs, and the current checkpoint 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, and current 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.
- [Rust SDK](https://smolmachines.com/docs/sdk/rust): The Rust crate, and the CLI its local target needs on the host.
- [Machine API](https://smolmachines.com/docs/sdk/machine-api): The Machine class: configuration, exec, run, files, and 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 machines.
- [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.

## 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

- [Your first internal tool](https://smolmachines.com/docs/guides/your-first-internal-tool): From empty folder to a deployed, private-by-default tool in three commands.
- [Run Python](https://smolmachines.com/docs/guides/python): Run Python code in a machine.
- [Run Node.js](https://smolmachines.com/docs/guides/nodejs): Run Node.js code 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.
- [Skill Packets](https://smolmachines.com/docs/guides/skills): Task-scoped procedures for smolvm, smol cloud and the SDKs, for an agent to load, each with its scripts and traps.
- [Install: set up smolvm and prove the host boots](https://smolmachines.com/docs/guides/skills/install): Install smolvm and prove the host boots a VM.
- [Teardown: stop everything and remove smolvm's state](https://smolmachines.com/docs/guides/skills/teardown): Stop every machine a session started and prove the host is clean.
- [Throwaway machine: run untrusted code with no network](https://smolmachines.com/docs/guides/skills/throwaway-machine): Run untrusted code with no network against a read-only repo.
- [Dev env: a persistent machine you re-enter](https://smolmachines.com/docs/guides/skills/dev-env): A persistent machine re-entered across sessions.
- [Local API: drive smolvm over HTTP](https://smolmachines.com/docs/guides/skills/local-api): Drive smolvm over its local HTTP API.
- [Docker in machine: run a Docker daemon inside a machine](https://smolmachines.com/docs/guides/skills/docker-in-machine): Run a Docker daemon inside a machine.
- [GPU CUDA: run CUDA workloads against a host GPU](https://smolmachines.com/docs/guides/skills/gpu-cuda): Run CUDA workloads against a host NVIDIA GPU.
- [Pack: ship a prepared machine as one file](https://smolmachines.com/docs/guides/skills/pack): Ship a prepared machine to another host as one file.
- [Branch and checkpoint: scheduled checkpoints, restores and branch points](https://smolmachines.com/docs/guides/skills/branch-and-checkpoint): Scheduled checkpoints with history, restores, pause and resume, and branch points.
- [Credentials: an API key the machine uses and never holds](https://smolmachines.com/docs/guides/skills/credentials): Let a workload use an API key it can never read.
- [Cloud auth: point an agent at a cloud account and prove it](https://smolmachines.com/docs/guides/skills/cloud-auth): Point an agent at a cloud account and prove one call works.
- [Cloud machine: create, drive and delete a cloud machine](https://smolmachines.com/docs/guides/skills/cloud-machine): Create, exec, move files, restart and delete a cloud machine.
- [Cloud registry: push an artifact and run a machine from it](https://smolmachines.com/docs/guides/skills/cloud-registry): Push an artifact and run a cloud machine from it.
- [Cloud errors: handle every failure the API returns](https://smolmachines.com/docs/guides/skills/cloud-errors): Every failure the cloud API returns, including the ones that arrive as 200.
- [Cloud usage: find out what a run cost](https://smolmachines.com/docs/guides/skills/cloud-usage): What a run cost, reconciled against uptime and the published rate.
- [SDK Python: drive cloud machines from Python](https://smolmachines.com/docs/guides/skills/sdk-python): Drive cloud machines from Python, install through delete.
- [SDK Node: drive cloud machines from Node](https://smolmachines.com/docs/guides/skills/sdk-node): Drive cloud machines from Node, install through delete.