# 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. Plain Markdown is available at https://github.com/smol-machines/docs; do not append .md to the website URLs.

## 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.
- [Forks and Snapshots](https://smolmachines.com/docs/introduction/concepts/forks-and-snapshots): Live copy-on-write clones, packs, and the current 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, 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.
- [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.