Secure code execution environment for AI-generated code using Firecracker microVMs
Website: https://runner.codes | Documentation: https://docs.runner.codes
Runner Codes is a secure execution environment for running code snippets generated by Large Language Models (LLMs) inside Firecracker microVMs. It provides strong isolation, fast boot times, and support for 45+ programming languages.
Firecracker is a Virtual Machine Monitor (VMM) developed by AWS that provides:
- Strong isolation: Full VM-level isolation, not just container namespaces
- Minimal footprint: ~5MB memory overhead per microVM
- Fast startup: Boots a VM in ~125ms (cold) or ~70ms (warm with snapshots)
- Security-first design: Built with a minimal device model and seccomp filters
- 45+ Languages: Python, Node.js, Go, Rust, Java, C/C++, and many more
- Fast Execution: ~70ms warm boot with snapshot restore
- Strong Isolation: Each execution runs in its own microVM
- Simple API: CLI and HTTP API for easy integration
- S3 Integration: Store and retrieve rootfs images from S3
- Linux with KVM support (
/dev/kvm) - Go 1.21+
Note: Firecracker does not run on macOS. Use an AWS EC2 metal instance or a Linux VM with nested virtualization.
# Download the binary (Linux x86_64)
curl -L -o infra.operator https://github.com/andrebassi/runner-codes/releases/latest/download/infra.operator-linux-amd64
chmod +x infra.operator
sudo mv infra.operator /usr/local/bin/
# Or for ARM64
curl -L -o infra.operator https://github.com/andrebassi/runner-codes/releases/latest/download/infra.operator-linux-arm64
# Run setup (installs Firecracker, kernel, creates directories)
sudo infra.operator setupSee all releases at github.com/andrebassi/runner-codes/releases
# Create Python rootfs from Docker image
sudo infra.operator rootfs from-docker --name python --image python:3.12-alpine --size 150sudo infra.operator snapshot create --lang python --mem 512 --vcpus 1# Using snapshot (warm boot - fast)
sudo infra.operator host --lang python --code "print('Hello from Firecracker!')" --mem 512 --vcpus 1 --snapshot
# Using HTTP API
infra.operator api --port 8080
curl -X POST http://localhost:8080/api/v1/execute \
-H "Content-Type: application/json" \
-d '{"language": "python", "code": "print(\"Hello from Firecracker!\")"}'Output:
{
"trace_id": "tr-1764485208308504533",
"status": "success",
"stdout": "Hello from Firecracker!\n",
"stderr": null,
"exit_code": 0,
"exec_time": "34ms"
}| Category | Languages |
|---|---|
| Popular | Python, Node.js, TypeScript, Go, Rust, Java, C# |
| Web | PHP, Ruby, Perl |
| Compiled | C, C++, Fortran, Pascal, COBOL |
| Functional | Haskell, OCaml, Elixir, Erlang, Clojure, Lisp |
| JVM | Java, Kotlin, Scala, Groovy |
| Modern | Zig, Nim, Crystal, D |
| Scientific | Julia, R, Octave |
| Scripting | Lua, Tcl, AWK, Bash |
| Database | SQLite, MySQL, PostgreSQL, MongoDB, Redis |
See the full Languages Reference for details.
┌─────────────────┐ ┌──────────────────────────┐ ┌─────────────────────┐
│ HTTP API │────▶│ infra.operator │────▶│ Firecracker microVM│
│ (port 8080) │ │ (unified CLI) │ │ │
└─────────────────┘ └──────────────────────────┘ │ ┌───────────────┐ │
│ │ │ guest runner │ │
│ vsock (CID=3) │ │ (port 5000) │ │
└──────────────────────────┼──│ │ │
│ └───────────────┘ │
└─────────────────────┘
| Component | Description |
|---|---|
infra.operator host |
Orchestrates Firecracker VMs on the host |
infra.operator guest |
Runs inside the microVM, executes code |
infra.operator api |
HTTP API server |
infra.operator rootfs |
Manages rootfs images |
infra.operator snapshot |
Manages VM snapshots |
| Boot Type | Time | Description |
|---|---|---|
| Cold Boot | ~3s | Full kernel boot + init |
| Warm Boot | ~70ms | Snapshot restore |
runner.codes/
├── cmd/
│ └── infra.operator/ # CLI entry point
├── pkg/
│ ├── host/ # Host-side VM control
│ ├── guest/ # Guest-side code execution
│ └── api/ # HTTP API server
├── internal/
│ ├── config/ # Language configurations
│ ├── rootfs/ # Rootfs builder
│ └── snapshot/ # Snapshot manager
├── docs/
│ └── docusaurus/ # Documentation site
├── aws/ # AWS deployment scripts
├── docker/ # Docker configurations
├── go.mod
├── Taskfile.yaml
└── README.md
sudo infra.operator setup # Full setup
sudo infra.operator setup --skip-docker # Skip Docker installationinfra.operator rootfs from-docker --name X --image Y --size Z # Create from Docker
infra.operator rootfs list # List local images
infra.operator rootfs upload --lang X --bucket Y # Upload to S3infra.operator snapshot create --lang X --mem Y --vcpus Z # Create snapshot
infra.operator snapshot list # List snapshotsinfra.operator host --lang X --code "..." --snapshot # Execute with snapshot
infra.operator host --lang X --code "..." --kernel /path # Execute cold bootinfra.operator api --port 8080 # Start API server| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Health check |
| GET | /api/v1/languages |
List supported languages |
| POST | /api/v1/execute |
Execute code |
| GET | /api/v1/rootfs |
List rootfs images |
| GET | /api/v1/snapshots |
List snapshots |
curl -X POST http://localhost:8080/api/v1/execute \
-H "Content-Type: application/json" \
-d '{
"language": "python",
"code": "print(sum(range(100)))",
"timeout": 10
}'For production or Mac users:
# Set credentials
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"
export AWS_DEFAULT_REGION="us-east-1"
# Launch EC2 metal instance
task aws:launch
# Deploy and test
task aws:deploy
task aws:test
# Cleanup
task aws:cleanup# Build all binaries
task build:all
# Cross-compile for Linux
GOOS=linux GOARCH=amd64 go build -o bin/infra.operator-linux ./cmd/infra.operator/...task test:unit # Unit tests
task test:coverage # With coverage
task test:coverage-html # HTML reportFull documentation is available at docs.runner.codes
sudo modprobe kvm
sudo modprobe kvm_intel # or kvm_amdsudo modprobe vhost_vsocksudo usermod -aG kvm $USER
# Logout and login againDeveloped by André Bassi