Quickstart - Podflare

Python
TypeScript
curl

pip install podflare

from podflare import Sandbox

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

npm install podflare

import { Sandbox } from "podflare";

const s = await Sandbox.create();
try {
  const r = await s.runCode("print(sum(range(10)))");
  console.log(r.stdout); // 45
} finally {
  await s.close();
}

# 1. create
SID=$(curl -s -X POST https://api.podflare.ai/v1/sandboxes \
  -H 'content-type: application/json' -d '{}' | jq -r .id)

# 2. exec (streams NDJSON events)
curl -s -X POST https://api.podflare.ai/v1/sandboxes/$SID/exec \
  -H 'content-type: application/json' \
  -d '{"code": "print(sum(range(10)))"}'

# 3. destroy
curl -s -X DELETE https://api.podflare.ai/v1/sandboxes/$SID

Configuration

PODFLARE_HOSTD_URL

string

default:"https://api.podflare.ai"

Base URL of the hostd HTTP API. In hosted mode this is set to the cloud endpoint; during local dev it’s the Hetzner box you tunneled to.

Run Python with persistent state

Each sandbox owns a long-lived Python process. Variables, imports, and any in-memory state survive across run_code calls.

with Sandbox() as s:
    s.run_code("import pandas as pd")
    s.run_code("df = pd.read_csv('/data/customers.csv')")
    s.run_code("print(df.shape)")  # pandas + df are both in scope

Fork for tree-search

This is the reason you chose Podflare. Set up expensive state once, then fork N ways. Each child inherits the parent’s Python REPL + filesystem — subsequent divergence is copy-on-write isolated.

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

    children = parent.fork(n=3)
    try:
        for c in children:
            print(c.run_code("print(json.dumps(cfg))").stdout)
    finally:
        for c in children:
            c.close()

Concepts: fork

How CoW branching + REPL inheritance actually works

API Reference

The full HTTP surface

Documentation Index

​Configuration

​Run Python with persistent state

​Fork for tree-search

​Next

Concepts: fork

API Reference

Configuration

Run Python with persistent state

Fork for tree-search

Next