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

# Sandboxes

> Remote containers your code creates on demand, with process control, a filesystem API, ports, snapshots, and optional Docker.

A sandbox fits running generated code, testing a patch, or giving an agent a
development environment. Each one is a container in the cloud that your code
starts, drives, and terminates.

## Create a sandbox

Save this as `sandbox_demo.py` and run it with `uv run python sandbox_demo.py`:

```python theme={null}
from lazycloud import App, Image

app = App("agents")

sandbox = app.sandbox(
    image=Image(python_version="3.12"),
    cpu=1.0,
    memory=1024,
    keep_warm_seconds=600,
)

instance = sandbox.create()
try:
    result = instance.run("python --version")
    print(result.exit_code, result.stdout)
finally:
    instance.terminate()
```

It prints exit code `0` and the sandbox's Python version. A sandbox bills until
it stops, so the `finally` block terminates it even when a command fails. A
plain number for `memory` means MiB.

### Reconnect to a running sandbox

Another process can reconnect by ID before the sandbox expires:

```python theme={null}
instance = sandbox.create()
sandbox_id = instance.sandbox_id()

same = sandbox.connect(sandbox_id)   # reconnect later
instance.update_ttl(1800)            # extend the idle lifetime
```

`sandbox.list()` returns the workspace's sandboxes, and `sandbox.stats()`
counts them.

## Use a running sandbox

### Commands and processes

`run` waits for the command to exit, and `process` controls long-running ones:

```python theme={null}
result = instance.run("pytest -q", cwd="/workspace", timeout_seconds=300)

proc = instance.process.exec("python", "-m", "http.server", "8000")
print(proc.status())
proc.kill()
proc.wait(timeout=10)

instance.process.run_code("print(2 + 2)")   # a Python snippet
instance.list_processes()
```

A process has `pid`, `status()`, `kill()`, `wait()`, and `stdout`, `stderr`, and
`logs` streams with `read()` and `lines()`.

### Files

`instance.fs` reads and writes the sandbox filesystem, rooted at `/workspace`:

```python theme={null}
instance.fs.upload_file("model.pt", "/workspace/model.pt")
instance.fs.download_file("/workspace/out.json", "out.json")
instance.fs.list_files("/workspace")
instance.fs.stat_file("/workspace/model.pt")
instance.fs.create_directory("/workspace/data")
instance.fs.delete_file("/workspace/tmp.txt")
instance.fs.find_in_files("/workspace/src", "TODO")
instance.fs.replace_in_files("/workspace/src", "old", "new")
```

### Ports and network

```python theme={null}
url = instance.expose_port(8000)
instance.list_urls()

instance.network_permissions()
instance.update_network_permissions(block_network=True)
instance.update_network_permissions(allow_list=["203.0.113.10/32"])
```

An exposed URL lives as long as the container. `ports=[8000]` on the sandbox
exposes ports at start. Outbound access is either blocked or limited to CIDR
ranges.

### Snapshots

```python theme={null}
snapshot_id = instance.snapshot_memory()
restored = sandbox.create_from_memory_snapshot(snapshot_id)

image_id = instance.create_image_from_filesystem()
```

A memory snapshot restores a running sandbox. A filesystem image captures the
disk for reuse with `Image.from_id(...)`.

### Async

Each API has an async form under `.aio`, such as `await instance.aio.run(...)`.

## Sandbox options

Sandboxes accept `env`, `secrets`, `volumes`, `gpu` and `gpu_count`,
`sync_local_dir=True` to copy your working directory in at creation,
`command` for the initial process, `ports`, `docker_enabled`, and `machine`.
`keep_warm_seconds` sets how long an idle sandbox stays up, 600 by default.

### Docker inside a sandbox

`image=Image().with_docker()` with `docker_enabled=True` runs a Docker daemon in
the sandbox, and `instance.docker` wraps `run`, `build`, `ps`, `logs`,
`compose_up`, and the rest. Nested containers share the sandbox's network, so
each service binds its own port and `instance.expose_port(port)` gives its URL.

## Stop and clean up

`instance.terminate()` stops a sandbox at once. Otherwise it stops after
`keep_warm_seconds` idle. The [dashboard](/platform/dashboard) shows running
sandboxes with a terminal, file browser, and process list.

## Shared settings

[Images](/concepts/images) and [resources](/concepts/resources).