⚡ FORKBOX
Deterministic, sub-millisecond execution runtime & sandboxing engine for Autonomous AI Agents.
Traditional container runtimes (Docker/containerd) introduce unacceptable latency overhead (~400ms per cold boot) for recursive agent workflows (e.g., Tree-of-Thought, SWE-bench, Code Execution). Heavy MicroVMs (Firecracker/gVisor) mitigate security concerns but penalize boot latency and consume excessive RAM.
Forkbox provides a hardened, rootless micro-sandbox designed specifically for ephemeral agent task execution, delivering up to 500x faster startup times than Docker with zero host disk contamination.
📊 Benchmarks (Real Hardware Validation)
Measured on bare-metal Ubuntu Linux (x86_64), execution: exit 0 / Python compute:
| Runtime Engine | Isolation Boundary | Cold Boot Latency | Speedup vs Docker |
|---|---|---|---|
Docker (alpine:latest) |
Namespaces + Daemon (runc) | 409.44 ms | 1.0x (Baseline) |
| Forkbox (Python 3.12 Runtime) | Rootless UserNS + Ephemeral OverlayFS | 26.39 ms | 15.5x faster |
| Forkbox (Hardened Shell) | UserNS + Seccomp-BPF + Cgroups v2 | 2.97 ms | 137.8x faster |
| Forkbox (RAW Isolation Hot-Path) | Direct Kernel Fork + CoW Pages | 0.713 ms (713 µs) | 574.0x faster |
Anti-DoS Watchdog precision: 500ms target killed at 500.45 ms (+450 µs jitter).
🛡️ Architectural Pillars
- Zygote Warm Pre-Mounting: Pre-warms base kernel namespaces (
PID,NET,IPC,UTS) in physical memory. Instances branch out via Copy-on-Write (fork()) bypassing dynamic linker (ld.so) overhead. - Ephemeral RAM OverlayFS: The host filesystem serves as an immutable
lowerdir=/. Each sandbox executes with an isolatedupperdirandworkdirmounted ontmpfs. File mutations vanish completely on process termination. - Ring 0 Seccomp-BPF Filtering: Injects compiled BPF bytecode directly into the kernel before execution. High-risk escape vectors (
mount,ptrace,bpf,reboot,init_module) return deterministicEPERMerrors. - 100% Rootless (Zero
sudo): Built natively on Linux User Namespaces (CLONE_NEWUSER). Unprivileged host users (UID 1000) safely obtain mappedUID 0privileges confined strictly inside the sandbox jail. - Sub-Millisecond Watchdog: Async event-loop monitors executions via non-blocking IPC pipes, delivering microsecond-precision
SIGKILLtermination against infinite loops (while true) and DoS scripts.
🚀 Quickstart
1. Build the Rust Engine
# Clone and compile optimized binary
git clone [https://github.com/matheusdelgado/forkbox.git](https://github.com/matheusdelgado/forkbox.git)
cd forkbox
cargo build --release
2. Start the Daemon
The daemon manages rootless namespaces and listens on /tmp/forkbox.sock:
./target/release/forkbox daemon
3. Install the Python SDK
In your agent environment:
pip install -e .
4. Use in Python (LangChain, AutoGen, or Raw Code)
from forkbox import Forkbox
# 1. Safe arbitrary code execution
res = Forkbox.run("python3 -c 'import math; print(math.factorial(20))'")
print(res.stdout) # "2432902008176640000"
print(f"Time: {res.duration_ms:.2f}ms") # ~26 ms
# 2. Strict DoS containment (Terminated automatically in 500ms)
res_loop = Forkbox.run("while true; do :; done", timeout_ms=500)
print(res_loop.timed_out) # True
print(res_loop.exit_code) # 124
# 3. Security check: Host system is completely untouchable
res_hack = Forkbox.run("echo 'payload' >> /etc/hosts")
# Writes happen in ephemeral RAM (OverlayFS) and evaporate on exit.
🔒 Security Architecture
[ Unprivileged Agent Code / Python Script ]
│
▼
[ Seccomp-BPF Jail ] ── (Blocks: ptrace, bpf, reboot, mount, kexec)
│
▼
[ User Namespace (CLONE_NEWUSER) ] ── (Host UID 1000 -> Jail UID 0)
│
▼
[ Ephemeral OverlayFS ] ── (upperdir: tmpfs in RAM | lowerdir: /)
│
▼
[ Linux Kernel (Ring 0) ]
📄 License
MIT License. Designed for deep-tech agent infrastructure.
Metadata
Release files for forkbox 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| forkbox-0.1.0.tar.gz | 5.5 kB | Without provenance | Details for forkbox-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| forkbox-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for forkbox-0.1.0-py3-none-any.whl |
Total release size: 11.0 kB
Release files / forkbox-0.1.0.tar.gz
| Download URL | forkbox-0.1.0.tar.gz |
|---|---|
| Size | 5.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
39ba862538f2b6c3d7d8ac067f8b06cadc72dd1447ba4e4ee61878492ad84055
|
|
BLAKE2b-256 checksum How to use checksums |
588c4970ceb63bdc25dea9fb7eff702859cd1800acb9fe5860c009d9ce9d55dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / forkbox-0.1.0-py3-none-any.whl
| Download URL | forkbox-0.1.0-py3-none-any.whl |
|---|---|
| Size | 5.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
263cd416043fb72bb39ceed9f1675f72cbecf57111a0963661fc7275195febf5
|
|
BLAKE2b-256 checksum How to use checksums |
94604d89b04328dd2cc196771eae8d3e06b7b942365d624d49f6bd9d38d354c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for forkbox 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.