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

# Sandbox

> Create sandboxes, run commands, and execute Python code.

## Overview

| Method                      | Description                                                        |
| :-------------------------- | :----------------------------------------------------------------- |
| `Sandbox.create()`          | Create a new sandbox                                               |
| `sandbox.commands.run(cmd)` | Run a command                                                      |
| `sandbox.code.run(code)`    | Run Python code                                                    |
| `sandbox.close()`           | Shut down the running sandbox (suspended instances are unaffected) |
| `sandbox.suspend()`         | Suspend to disk, returns an instance ID                            |
| `Sandbox.resume(id)`        | Resume a suspended instance                                        |
| `Sandbox.list_instances()`  | List all instances                                                 |
| `Sandbox.destroy(id)`       | Delete a suspended instance from disk                              |

Shell commands and Python code share the same filesystem:

```python theme={null}
from vpod import Sandbox

with Sandbox.create() as sandbox:
    sandbox.commands.run("echo 'from shell' > /tmp/shared.txt")
    sandbox.code.run("print(open('/tmp/shared.txt').read().strip())")
```

<Warning>
  Environment variables don't cross between shell and Python: `sandbox.commands.run("export FOO=bar")` is not visible in `sandbox.code.run(...)`. Use the filesystem to share data between the two.
</Warning>

## `Sandbox.create()` parameters

### `snapshot`

The snapshot to boot from. Defaults to `alpine`. See [Snapshots](/sdk/snapshots) for the full catalog.

```python theme={null}
sandbox = Sandbox.create(snapshot="alpine")
```

### `mounts`

Mount host directories into the sandbox. Paths are read-only by default; append `:rw` for read-write access.

```python theme={null}
sandbox = Sandbox.create(mounts={"workspace": "/workspace:rw", "docs": "/docs"})
```