> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celesto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SmolVM: secure microVM sandboxes for AI agents

> Introduction to SmolVM — an open-source microVM sandbox with sub-second boot, hardware isolation, and persistent state for running AI agents safely.

# SmolVM

[SmolVM](https://github.com/CelestoAI/SmolVM) gives AI agents their own disposable computer. Each <Tooltip tip="A lightweight virtual machine that provides hardware-level isolation with near-instant startup, combining the speed of containers with the security of full VMs">microVM</Tooltip> boots in milliseconds, runs any code or software you throw at it, persists files and state across sessions, and disappears when you're done — built for scale in production.

<CardGroup cols={3}>
  <Card title="Sub-second boot" icon="bolt">
    VMs ready in \~413 ms.
  </Card>

  <Card title="Hardware isolation" icon="shield">
    Stronger security than containers.
  </Card>

  <Card title="Network controls" icon="filter">
    Domain allowlists for network access control.
  </Card>

  <Card title="Browser sandbox" icon="globe">
    Full browser agents can see and control.
  </Card>

  <Card title="Host mounts" icon="folder-open">
    Give sandboxes access to local directories.
  </Card>

  <Card title="Snapshots" icon="camera">
    Save and restore VM state instantly.
  </Card>
</CardGroup>

<Note>
  **Building with agent sandboxes?** Get SmolVM release notes, implementation patterns, and early-access updates.

  [Join the SmolVM interest list][smolvm-interest-list]
</Note>

## Quickstart

<Steps>
  <Step title="Install SmolVM">
    ```bash theme={null}
    curl -sSL https://celesto.ai/install.sh | bash
    ```

    This installs everything you need and configures your machine. See [Installation](/smolvm/installation) for manual install and requirements.
  </Step>

  <Step title="Run your first sandbox">
    <Tabs>
      <Tab title="Python">
        Create `quickstart.py`:

        ```python quickstart.py theme={null}
        from smolvm import SmolVM

        vm = SmolVM()
        result = vm.run("echo 'Hello from the sandbox!'")
        print(result.stdout.strip())
        vm.stop()
        ```

        Run it:

        ```bash theme={null}
        python quickstart.py
        ```
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        smolvm sandbox create --name my-sandbox
        smolvm sandbox ssh my-sandbox
        echo 'Hello from the sandbox!'
        exit
        smolvm sandbox stop my-sandbox
        ```
      </Tab>
    </Tabs>

    You should see:

    ```text theme={null}
    Hello from the sandbox!
    ```
  </Step>
</Steps>

### CLI usage

Create and manage sandboxes from the terminal:

```bash theme={null}
smolvm sandbox create --name my-sandbox
smolvm sandbox ssh my-sandbox
smolvm sandbox list
smolvm sandbox stop my-sandbox
```

Run coding agents in an isolated sandbox:

```bash theme={null}
smolvm claude start
smolvm codex start
smolvm pi start
```

Mount host directories for read-only access:

```bash theme={null}
smolvm sandbox create --mount ~/Projects/my-app
smolvm sandbox create --mount ~/Projects/my-app:/code --mount ~/data:/mnt/data
```

Save and restore VM state with snapshots:

```bash theme={null}
smolvm sandbox snapshot create my-sandbox
smolvm sandbox snapshot list
smolvm sandbox snapshot restore snap_abc123 --resume
```

Start a visible browser sandbox:

```bash theme={null}
smolvm browser start --live
smolvm browser list
smolvm browser stop sess_a1b2c3
```

See the [CLI reference](/smolvm/cli/overview) for the full command list.

### Python SDK

Create and manage sandboxes from Python:

```python theme={null}
from smolvm import SmolVM

with SmolVM() as vm:
    result = vm.run("echo 'Hello from the sandbox!'")
    print(result.stdout.strip())
```

Customize memory and disk for heavier workloads:

```python theme={null}
vm = SmolVM(memory=2048, disk_size=4096)
```

Mount host directories:

```python theme={null}
with SmolVM(mounts=["~/Projects/my-app"]) as vm:
    result = vm.run("ls /workspace")
    print(result.stdout)
```

Expose a port from the sandbox to your host:

```python theme={null}
with SmolVM() as vm:
    vm.run("python3 -m http.server 8000 &")
    host_port = vm.expose_local(guest_port=8000)
    print(f"http://127.0.0.1:{host_port}/")
```

See the [API reference](/smolvm/api/smolvm) for the full SDK documentation.

<Tip>
  Evaluating secure code execution, browser agents, or long-running agent environments? [Tell us what you're building][smolvm-interest-list] and we'll send the useful SmolVM updates — or follow up personally if you're evaluating now.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="AI agent integration" icon="robot" href="/smolvm/guides/ai-agent-integration">
    Plug SmolVM into PydanticAI, OpenAI Agents, LangChain, and more
  </Card>

  <Card title="Port forwarding" icon="network-wired" href="/smolvm/features/port-forwarding">
    Expose services running inside a sandbox to your host machine
  </Card>

  <Card title="Custom images" icon="box" href="/smolvm/guides/custom-images">
    Build specialized images with your own tools pre-installed
  </Card>

  <Card title="API reference" icon="book" href="/smolvm/api/smolvm">
    Explore the complete SmolVM API
  </Card>
</CardGroup>

[smolvm-interest-list]: https://tally.so/r/yPGeJd?utm_source=docs&utm_medium=smolvm_intro&utm_campaign=email_capture