Skip to main content
Podflare sandboxes run your agent’s code in isolated Firecracker microVMs that spin up in 7–11 ms. This guide walks you through installing the SDK, authenticating, and running your first code — including how persistent REPL state and forking work in practice.
1

Install the SDK

Install the Podflare SDK for your language from PyPI or npm.
pip install podflare
2

Set your API key

Export your Podflare API key as an environment variable. The SDK reads it automatically — no additional configuration required.
export PODFLARE_API_KEY=pk_your_key_here
Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) or your project’s .env file so you don’t have to set it each session.
3

Create a sandbox and run code

Create a sandbox, execute code, and read the output. The sandbox closes automatically when the with block exits (Python) or when you call close() (TypeScript).
from podflare import Sandbox

with Sandbox() as s:
    r = s.run_code("print(sum(range(10)))")
    print(r.stdout)  # 45

​
Use persistent REPL state

Each sandbox owns a long-lived Python process. Variables, imports, and any in-memory state survive across run_code calls — so you can load data once and operate on it across multiple steps. 
from podflare import Sandbox

with Sandbox() as s:
    s.run_code("import pandas as pd")
    s.run_code("df = pd.read_csv('/data/customers.csv')")
    r = s.run_code("print(df.shape)")  # pandas and df are both in scope
    print(r.stdout)
Persistent state is scoped to the sandbox. When the sandbox closes, all state is discarded. Fork the sandbox before closing if you want to branch from a particular checkpoint.

​
Fork for parallel exploration

fork(n) snapshots the parent sandbox and spawns N isolated children. Each child inherits the parent’s full Python REPL state — variables, imports, loaded files — then diverges independently using copy-on-write. This lets your agent set up expensive state once and explore multiple strategies in parallel.
This is the reason to choose Podflare over a plain code execution API. Load a large dataset or run a costly setup step once in the parent, then fork N ways for free.
from podflare import Sandbox

with Sandbox() as parent:
    parent.run_code("import json; cfg = {'temp': 0.7}")

    children = parent.fork(n=3)
    try:
        for c in children:
            # Each child has cfg already in scope
            print(c.run_code("print(json.dumps(cfg))").stdout)
    finally:
        for c in children:
            c.close()
Once you pick a winning child, call parent.merge_into(winner) to promote that child’s state back to the parent and continue from there.

​
Next steps

Concepts: fork

How copy-on-write branching and REPL inheritance work under the hood

Concepts: persistent REPL

What survives across run_code calls and what doesn’t

Integrations

Drop-in tools for OpenAI Agents SDK, Anthropic, and Vercel AI SDK

API reference

The full HTTP surface for sandboxes, exec, fork, and merge