gitvm
Self-hosted sandbox platform with Firecracker & Docker runtimes
Quickstart ·
Architecture ·
SDK ·
Cloud Deployment ·
API
gitvm is a self-hosted alternative to E2B for running isolated sandbox environments. Give your AI agents a full Linux VM to write code, run tests, and execute commands — on your own infrastructure.
SDK → REST API → Orchestrator → Firecracker VM or Docker Container → Guest Agent
Quickstart
Install
go install github.com/open-gitagent/gitvm/cmd/gitvm@latest
Start the server
gitvm server start --port 8080
Create and use a sandbox
# Create a sandbox
gitvm vm create --template ubuntu:22.04 --vcpus 2 --memory 1024
# Execute a command
gitvm vm exec <sandbox-id> "echo hello world"
# List running sandboxes
gitvm vm list
# Stop a sandbox
gitvm vm stop <sandbox-id>
Use as a Go SDK
package main
import (
"context"
"fmt"
"github.com/open-gitagent/gitvm/sdk"
)
func main() {
machine := sdk.NewGitVMMachine(sdk.GitVMConfig{
ServerURL: "http://localhost:8080",
Template: "ubuntu:22.04",
VCPUs: 2,
MemoryMB: 1024,
})
ctx := context.Background()
machine.Start(ctx)
defer machine.Stop(ctx)
result, _ := machine.Execute(ctx, "cat /etc/os-release", nil)
fmt.Println(result.Stdout)
}
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Control Plane (gitvmd) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ REST API │ │ Scaler │ │ Auth │ │ Dashboard │ │
│ └────┬─────┘ └────┬─────┘ └──────────┘ └────────────┘ │
│ │ │ │
│ │ ┌─────────┴──────────┐ │
│ │ │ Cloud Providers │ │
│ │ │ AWS · GCP · Azure │ │
│ │ └────────────────────┘ │
└───────┼─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Node (gitvm-node) │
│ ┌──────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ Orchestrator │ │ Docker Runtime │ │ FC Runtime │ │
│ │ │ │ │ │ (Firecracker) │ │
│ └──────┬───────┘ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Sandbox 1 │ │ Sandbox 2 │ ... │ Sandbox N │ │
│ │ ┌────────┐ │ │ ┌────────┐│ │ ┌────────┐│ │
│ │ │ Agent │ │ │ │ Agent ││ │ │ Agent ││ │
│ │ └────────┘ │ │ └────────┘│ │ └────────┘│ │
│ └────────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────┘
Three binaries
| Binary |
Role |
Runs on |
gitvmd |
Control plane — manages nodes, projects, API keys, auto-scaling |
Central server |
gitvm-node |
Node agent — manages sandboxes on a single host |
Each cloud VM |
gitvm |
CLI + guest agent — user-facing commands + in-sandbox daemon |
Everywhere |
Pluggable runtimes
|
Docker |
Firecracker |
| Isolation |
Container-level |
Hardware VM (KVM) |
| Startup |
~1s |
~125ms |
| Overhead |
Shared kernel |
Dedicated kernel |
| Requirements |
Docker installed |
KVM (/dev/kvm) |
| Snapshots |
docker commit |
VM snapshots |
| Best for |
Dev/testing, Mac |
Production, Linux |
Features
- Sandbox lifecycle — create, pause, resume, stop, destroy
- Command execution — run any command inside a sandbox, get stdout/stderr/exit code
- Filesystem access — read, write, list, mkdir, delete files inside sandboxes
- Snapshots — freeze a sandbox, restore it later with all state preserved
- Templates — build custom rootfs images with your tools pre-installed
- Auto-scaling — control plane scales nodes up/down based on capacity
- Multi-cloud — provision nodes on AWS, GCP, or Azure
- Runtime-aware provisioning — auto-selects instance types (KVM-capable for Firecracker, standard for Docker)
- SDK — Go client implementing
gitmachine-go Machine interface
Cloud Deployment
The control plane auto-provisions nodes on AWS, GCP, or Azure. Each node installs gitvm from GitHub on boot:
go install github.com/open-gitagent/gitvm/cmd/gitvm-node@latest
go install github.com/open-gitagent/gitvm/cmd/gitvm@latest
Default instance types
| Provider |
Firecracker |
Docker |
| AWS |
c8i.xlarge (4 vCPU, 8 GB) |
t3.xlarge (4 vCPU, 16 GB) |
| GCP |
n2-standard-16 + nested virt |
e2-standard-4 |
| Azure |
Standard_D16s_v5 |
Standard_B4ms |
Start the control plane
gitvmd start \
--port 7070 \
--node-key "your-shared-secret" \
--aws-access-key $AWS_ACCESS_KEY_ID \
--aws-secret-key $AWS_SECRET_ACCESS_KEY \
--aws-region us-east-1
API Reference
All endpoints are served by gitvm-node (port 9090) or gitvm server (port 8080).
Sandboxes
POST /sandboxes Create sandbox
GET /sandboxes List sandboxes
GET /sandboxes/:id Get sandbox
DELETE /sandboxes/:id Delete sandbox
POST /sandboxes/:id/start Start stopped sandbox
POST /sandboxes/:id/stop Stop sandbox
POST /sandboxes/:id/pause Pause sandbox
POST /sandboxes/:id/resume Resume sandbox
Execution
POST /sandboxes/:id/exec Execute command
{ "command": "echo hello", "cwd": "/home", "timeout": 30 }
{ "exitCode": 0, "stdout": "hello\n", "stderr": "" }
Files
GET /sandboxes/:id/files?path= Read file
PUT /sandboxes/:id/files?path= Write file
GET /sandboxes/:id/files/list?path= List directory
POST /sandboxes/:id/files/mkdir?path= Create directory
DELETE /sandboxes/:id/files?path= Delete file
Snapshots
POST /sandboxes/:id/snapshot Create snapshot
POST /snapshots/:id/restore Restore from snapshot
DELETE /snapshots/:id Delete snapshot
GET /snapshots List snapshots
Building from source
git clone https://github.com/open-gitagent/gitvm.git
cd gitvm
# Build all binaries
make build
# Or individually
make build-cli # bin/gitvm
make build-node # bin/gitvm-node (linux/amd64)
make build-controlplane # bin/gitvmd
# Run tests
make test
Compared to E2B
|
E2B |
gitvm |
| Hosting |
Managed cloud |
Self-hosted |
| Protocol |
gRPC + Protobuf |
HTTP/JSON |
| Auth |
Supabase JWT |
API key |
| State |
PostgreSQL + Redis |
SQLite + in-memory |
| Templates |
GCS |
Local filesystem |
| Orchestration |
Nomad + Consul |
Single binary |
| Runtime |
Firecracker only |
Firecracker + Docker |
| Cost |
Per-sandbox pricing |
Your cloud costs |
License
MIT