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

# Python SDK

> from podflare import Sandbox

## Install

```bash theme={null}
pip install podflare
```

Requires Python 3.10+.

## Configuration

```python theme={null}
from podflare import Sandbox, Client

# Default: reads PODFLARE_HOSTD_URL env var, falls back to https://api.podflare.ai
sbx = Sandbox()

# Explicit host
sbx = Sandbox(host="https://api.podflare.ai")

# Share a Client across many sandboxes (avoids per-sandbox httpx.Client)
client = Client(host="https://api.podflare.ai")
a = Sandbox(client=client)
b = Sandbox(client=client)
```

## Core verbs

### `run_code(code, language="python") -> ExecResult`

Blocks until the code finishes, returns `ExecResult(stdout, stderr, exit_code)`.

```python theme={null}
r = sbx.run_code("print(sum(range(10)))")
assert r.exit_code == 0
assert r.stdout.strip() == "45"
```

### `run_code_stream(code, language="python") -> Iterator[Event]`

Yields events as they arrive.

```python theme={null}
for ev in sbx.run_code_stream("for i in range(3): print(i)"):
    if ev.type == "stdout":
        print(ev.data, flush=True)
    elif ev.type == "exit":
        print("done, exit", ev.data)
```

### `fork(n=1) -> list[Sandbox]`

See [Fork](/concepts/fork) for semantics.

```python theme={null}
children = parent.fork(n=5)
```

### `diff(other, paths=None) -> dict`

Filesystem diff against another sandbox.

```python theme={null}
d = a.diff(b)
# {"added": [...], "removed": [...], "modified": [...]}
```

### `merge_into(winner) -> None`

Commit a winner fork as the new state.

```python theme={null}
parent.merge_into(winner)
```

### `upload(data, remote_path) -> None` and `download(remote_path) -> bytes`

Small-file transfer (best for files up to a few MB).

```python theme={null}
sbx.upload(b"hello", "/root/hello.txt")
assert sbx.download("/root/hello.txt") == b"hello"
```

### `close() / context manager`

```python theme={null}
# Preferred:
with Sandbox() as s:
    ...  # destroyed automatically

# Manual:
s = Sandbox()
try:
    ...
finally:
    s.close()
```

## Framework adapters

<CardGroup cols={2}>
  <Card title="OpenAI Agents SDK" icon="robot" href="/integrations/openai-agents">
    `from podflare.integrations.openai_agents import podflare_code_interpreter`
  </Card>

  <Card title="Anthropic Messages API" icon="anthropic" href="/integrations/anthropic">
    `from podflare.integrations.anthropic import handle_code_execution_tool_use`
  </Card>
</CardGroup>

## Typing

The SDK ships full type annotations. `ExecResult`, `Event`, and `Language`
are importable from the top-level module.

```python theme={null}
from podflare import ExecResult, Event, Language
```