Firebreak

Firebreak

Function-level sandboxing for Python. Run untrusted code safely using Firecracker microVMs with a simple decorator API.

Python Firecracker MicroVM Sandboxing
hyperclast/firebreak โ†’

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.

This is real isolation, enforced at the OS/VM boundary. Decorators provide developer ergonomics, not security. MicroVMs provide security.

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