Skip to main content
A Podflare sandbox is a self-contained Firecracker microVM running on Podflare infrastructure. Unlike a container, it has a dedicated Linux kernel, private memory, and an isolated filesystem — so your code executes in a genuine hardware boundary, not a shared kernel namespace. Every sandbox also starts a persistent Python REPL at boot, meaning the state you build across run_code calls stays in scope without any extra setup.

​
What you get in every sandbox

Each sandbox includes:
  • A dedicated Linux kernel (guest kernel 6.1) and 2 vCPUs by default
  • ~1 GiB RAM by default (see resource limits)
  • A private 2 GB ext4 rootfs (Ubuntu 24.04 minimal)
  • A persistent Python REPL started at boot — variables, imports, and open file handles survive across calls
  • A private filesystem isolated from every other sandbox — writes are copy-on-write from a shared base image

​
Sandbox lifecycle

create ──► exec, exec, exec, fork, ... ──► destroy
   7ms            each ~few ms                ~50ms
Creating a sandbox returns in 7–11 ms when the warm pool has a pre-booted VM ready. Each run_code call adds a few milliseconds. Destroying a sandbox frees all resources in ~50 ms.
Because each sandbox holds a live Python process, run_code calls are not independent — later calls see the variables, imports, and open files set by earlier calls. Create a new sandbox when you want a clean slate.

​
Create, use, and destroy a sandbox

from podflare import Sandbox

# Context manager handles create and destroy automatically
with Sandbox() as s:
    r = s.run_code("x = 42; import json")
    r2 = s.run_code("print(x, json.dumps({'ok': True}))")
    print(r2.stdout)  # 42 {"ok": true}

​
Fast creation: the warm pool

Podflare keeps a pool of pre-booted VMs ready so create() doesn’t wait for a cold kernel boot. On a pool hit, your sandbox is ready in 7–11 ms. On a pool miss (burst traffic), creation falls back to a cold boot (~1.4 s) while the pool refills in the background. See Warm Pool for what to expect during bursts and how the pool recovers.

​
Isolation guarantees

Podflare sandboxes use Firecracker microVMs, not containers:
  • KVM hardware boundary — your code cannot access another sandbox’s memory at the kernel level
  • Dedicated guest kernel — no shared kernel with other tenants
  • Copy-on-write filesystem — each sandbox gets its own reflink of the base rootfs; writes only touch your VM
  • No outbound network by default — sandboxes boot without a network interface, preventing data exfiltration from LLM-authored code
Allowlisted egress (letting sandboxes call specific external domains) is coming in a future release. See Network & Egress for the current data-in/data-out patterns.

​
Resource limits

​
vcpu_count
int
default:"2"
Number of vCPUs allocated to the sandbox VM.
​
mem_size_mib
int
default:"1024"
Memory allocated to the sandbox in MiB. The default is 1024 MiB (~1 GiB).
Per-sandbox resource overrides are coming in a future release. For now, the defaults apply to all sandboxes.

Fork

Branch a running sandbox N ways with copy-on-write isolation

Python REPL

How state persists across run_code calls

Warm Pool

Why create() returns in under 11 ms

Network & Egress

How to move data in and out of a sandbox