podflare 0.0.22

Podflare Python SDK — cloud sandbox for AI agents with 100ms fork() and persistent REPL.

Podflare — Python SDK

Cloud sandbox for AI agents. Fork in 100 ms, persistent Python REPL, run_code, upload/download, merge_into, interactive PTY sessions (pty.create / attach / sendInput / resize / kill).

• Docs: https://docs.podflare.ai
• Dashboard: https://dashboard.podflare.ai — mint an API key in seconds
• GitHub: https://github.com/PodFlare-ai/podflare

Install

pip install podflare

Quickstart

from podflare import Sandbox

# Create a sandbox (persistent Python REPL, preloaded libs on python-datasci)
sbx = Sandbox(template="python-datasci")

# Execute code — state persists across calls
sbx.run_code("x = 42")
print(sbx.run_code("print(x * 2)").stdout)  # "84"

# Fork — spawn N copies of the running sandbox
children = sbx.fork(n=5)
children[0].run_code("x = 100")   # isolated per branch

# Merge a branch back into the parent
sbx.merge_into(children[0])

# Upload + download files
sbx.upload("data.csv", open("local.csv", "rb").read())
sbx.run_code("import pandas as pd; df = pd.read_csv('data.csv')")

# Destroy
sbx.close()

Configuration

Env var	Default	What it does
PODFLARE_API_KEY	(none — required)	Bearer token from the dashboard (pf_live_...).
PODFLARE_HOSTD_URL	https://api.podflare.ai	Override for self-hosted or staging deployments.

You can also pass them as constructor arguments:

from podflare import Sandbox

sbx = Sandbox(
    host="https://api.podflare.ai",
    api_key="pf_live_...",
    template="default",
)

Streaming

with Sandbox() as s:
    for ev in s.run_code_stream("for i in range(3): print(i)"):
        if ev.type == "stdout":
            print(ev.data, flush=True)

Interactive PTY — sandbox.pty.*

When an LLM-generated command needs a real terminal (interactive installers, REPLs, npm init, apt install, or anything that checks isatty()), reach for the PTY namespace. It gives you a first-class pseudo-terminal inside the sandbox, with reconnect support for long-running sessions that outlive your process.

from podflare import Sandbox

with Sandbox(region="eu") as sbx:
    # Spawn a real tty. timeout_ms=0 keeps the session alive until
    # close() or the sandbox's max_lifetime.
    pty = sbx.pty.create(
        cmd="npm init",
        cols=120, rows=40,
        on_data=lambda chunk: print(chunk.decode(), end=""),
        timeout_ms=0,
    )

    # Send keystrokes — strings are UTF-8, bytes are raw
    pty.send_input("\r" * 9)              # accept every npm init default
    pty.send_input(b"\x03")               # Ctrl-C
    pty.resize(cols=200, rows=50)         # child receives SIGWINCH
    exit_code = pty.wait()                # blocks until the child exits

Reconnect across turns (survive network blips)

# Turn 1 — kick off a long build
pty = sbx.pty.create(cmd="bash", timeout_ms=0)
pty.send_input(b"./build.sh 2>&1 | tee /tmp/build.log\n")
pty_id = pty.id  # persist this across your agent's turns

# Turn 2 (different process, maybe hours later)
pty = sbx.pty.attach(pty_id, on_data=stream_to_user)
# Replays the last 1 MiB of buffered output, then tails live.
# Same running bash — pty.send_input still works.

Full API: https://docs.podflare.ai/concepts/pty

Framework adapters

First-class integrations:

• OpenAI Agents SDK — podflare.adapters.openai_agents
• Anthropic code_execution tool — podflare.adapters.anthropic
• MCP server (podflare-mcp npm package) for Claude Desktop / Cursor / Cline / Zed

See the integrations docs for copy-paste examples.

Links

• Documentation
• API reference
• Status
• Issues

License

Proprietary.