Firebreak
Function-level sandboxing for Python. Run untrusted code safely using Firecracker microVMs with a simple decorator API.
Why Firebreak?
Python has no built-in sandboxing. Running untrusted code โ whether from users, plugins, or AI โ means giving it full access to your system. Firebreak fixes this by executing decorated functions inside lightweight Firecracker microVMs.
How It Works
from firebreak import firebreak
@firebreak(net=False, fs="ro:/data")
def process_untrusted_input(data: str) -> dict:
# This runs in an isolated microVM
# No network access, read-only filesystem
return parse_and_transform(data)
# Call it like any normal function
result = process_untrusted_input(user_data)
At import time, the decorator replaces the function with an RPC stub. When called, arguments are serialized and sent to a warm microVM from a pool. The result (or exception) is returned transparently.
Key Concepts
๐ Real Isolation
Functions run in Firecracker microVMs. Filesystem, network, CPU, and memory are enforced at the VM boundary โ not by Python tricks.
โก Warm VM Pools
VMs are pre-booted and ready. No cold start on the hot path. Pools are keyed by capability profile for efficient reuse.
๐ฏ Capability Profiles
Define what each sandbox can access: net=none, fs=ro:/data,
net=https-only. Each profile gets its own VM pool.
๐ฆ Simple API
Just a decorator. Functions must be top-level importable with serializable inputs/outputs. No closures, no implicit state.
Performance
This system trades raw call speed for strong isolation. That's the point.
| Execution Model | Typical Overhead |
|---|---|
| In-process Python call | ~0.1โ1 ยตs |
| Thread/coroutine dispatch | ~1โ5 ยตs |
| Warm microVM (Firebreak) | ~1โ10 ms |
| Cold microVM boot | 100โ500+ ms |
Rule of thumb: if the function's own work takes <1ms, sandboxing will dominate. If it takes 10โ100+ ms, overhead is usually acceptable.
Use Cases
- AI-generated code โ Run LLM outputs safely
- User plugins โ Let users extend your app without risk
- Data processing โ Parse untrusted files in isolation
- Policy enforcement โ Sandbox security-sensitive operations
- Multi-tenant execution โ Isolate customer workloads
FAQ
Do I need Firecracker installed?
Yes, Firebreak uses Firecracker microVMs for isolation. You'll need a Linux host with KVM support. For development, you can run Firecracker in a VM or use our provided Docker setup.
What about WASM or containers?
MicroVMs provide stronger isolation than containers and don't have WASM's Python compatibility issues. Firecracker boots in ~125ms and has minimal overhead once warm.
Can functions call back to the host?
Not in v1. Functions must be self-contained. Cross-VM communication and host callbacks are on the roadmap for v2.
What about closures and global state?
Decorated functions must be top-level importable with no closures or ambient state. This is intentional โ explicit boundaries make the security model clear.
How is serialization handled?
JSON-compatible types by default. Optional cloudpickle support for complex objects, but treat pickle as code injection โ never accept pickles from untrusted sources.
Get Started
Ready to sandbox some functions?
pip install firebreak