sand

<p align="center"> <img src="assets/logo.png" alt="sand" width="300" height="300" /> </p> <h1 align="center">sand</h1> **A ~3 MB static binary that turns bare Linux machines into a multi-machine compute platform.** Hardware-isolated [Firecracker](https://firecracker-microvm.github.io/) microVMs that boot in milliseconds - managed through a CLI, HTTP API, MCP server, or Go library. ## Why sand - **Install in seconds** - one `curl`, no Docker, no orchestrator, no runtime to manage. - **One command to set up your host** - `sand host setup` downloads Firecracker, fetches a kernel, creates the bridge, configures iptables, and creates jailer users. Done. - **VMs in <5ms** - warm pools give you a ready VM faster than most containers cold-start. - **Hardware-enforced isolation** - every VM is a Firecracker microVM. Not a container. Separate kernel, separate memory, separate network. - **Run code without SSH** - exec and file transfer work over vsock. The guest agent is auto-injected into every VM. Nothing to configure. - **Lock down network per VM** - allow-list `pypi.org` and `github.com`, block everything else. One flag at creation time. - **Know when things break** - OOM detection gives you structured feedback when a VM runs out of memory. - **Monitor everything from the host** - per-VM CPU, memory, network, and disk metrics via cgroups. No monitoring agent inside the VM. - **Push metrics to Datadog, Grafana, anywhere** - built-in OTLP export. Not a plugin, just a flag. - **Pre-bake your environments** - templates let you bake Python, Node, or any toolchain into a rootfs once. Every VM starts ready. - **Data that survives restarts** - persistent ext4 volumes attach to any VM. - **Attach volumes at any time** - hot-swap or stop-attach-start persistent volumes on any VM. - **Run 100+ VMs on one box** - fleet mode handles the concurrency, with isolation test suites that prove VMs can't see each other. - **No VM leaks** - TTL and idle timeouts auto-destroy everything. Walk away and nothing lingers. - **Snapshots you can restore** - timestamped rootfs snapshots with prune and one-command restore. - **Portable backups** - tar.gz or restic-powered backups with dedup, encryption, and S3 support. Back up locally or off-host for real disaster recovery. - **Resize on the fly** - grow disk on running VMs, or stop-resize-start for vCPU and memory changes. - **Export and import VMs** - migrate VMs between hosts with `sand vm export` and `sand vm import`. - **Build your own tools on top** - OpenAPI spec ships with every release. Generate a TypeScript SDK in one command. - **Embed it in Go** - sand is library-first. Every CLI command is a thin wrapper you can call from your own programs. - **React to events in real time** - SSE stream for VM lifecycle events. Build dashboards, trigger workflows, or integrate with any automation. - **Docker UX you already know** - `sand run`, `sand ps`, `sand rm`, `sand logs`. If you know Docker, you know sand. - **Script everything** - `--json` output on every command. Pipe, parse, automate. - **Tab-complete everything** - shell completion for bash, zsh, and fish out of the box. - **HTTP API with auth** - `sand serve` gives you a full REST API with optional bearer token. Not just a CLI tool. - **MCP server built in** - `sand mcp` exposes VM management as MCP tools, so any MCP-compatible client can provision and control VMs directly. - **Your hardware, your data** - self-hosted, no per-second billing, no vendor API, nothing leaves your machine. > [!TIP] > New here? Jump straight to the [Quick Start](docs/quickstart.md) - zero to a running VM in under 5 minutes. ## Install ```bash curl -Lo /usr/local/bin/sand \ https://github.com/nixopus/sand/releases/latest/download/sand-linux-amd64 curl -Lo /usr/local/bin/sand-agent \ https://github.com/nixopus/sand/releases/latest/download/sand-agent-linux-amd64 chmod +x /usr/local/bin/sand /usr/local/bin/sand-agent ``` That's it. Or `go install github.com/nixopus/sand/cmd/sand@latest` from source. See the full [Installation guide](docs/install.md) for distro-specific setup and cloud provider notes. ## Quick start ```bash sand host setup # one-time: download Firecracker, create bridge sand run my-vm --ssh-key ~/.ssh/id.pub # boot a VM sand exec my-vm -- python script.py # run code inside it (no SSH) sand cp script.py my-vm:/workspace/ # push files in sand stats my-vm # CPU, memory, network, disk sand rm my-vm # tear it down ``` Start the HTTP API or MCP server with one command: ```bash sand serve --port 8080 # REST API for programmatic access sand mcp # MCP server for tool-aware clients ``` ## Library usage ```go hc := sand.DefaultHostConfig() sand.NewHostManager(hc).Setup(context.Background()) vm := sand.NewVMManager(sand.VMConfig{ Name: "worker", GuestIP: "10.0.2.5", GatewayIP: hc.Bridge.IP, SubnetMask: "255.255.0.0", SSHHostPort: 2205, KernelPath: hc.Paths.KernelPath, BaseRootfs: hc.Paths.BaseRootfs, RootfsDir: hc.Paths.RootfsDir, BridgeName: hc.Bridge.Name, }, hc.Paths) vm.Create(context.Background()) result, _ := sandbox.Exec(ctx, vm, sandbox.ExecRequest{ Cmd: []string{"python", "script.py"}, Dir: "/workspace", }) fmt.Println(result.Stdout) ``` ## Documentation | Guide | What you'll learn | |-------|-------------------| | [Installation](docs/install.md) | How to install sand, set up your host, and get ready for your first VM | | [Quick Start](docs/quickstart.md) | Go from zero to a running VM in under 5 minutes | | [Usage Guide](docs/usage.md) | Everything you can do with sand - VMs, templates, snapshots, fleet mode, monitoring, and more | | [HTTP API](docs/api.md) | Control VMs programmatically over REST, with SSE events and OpenAPI spec | | [MCP Server](docs/mcp.md) | Expose VM management as MCP tools for any compatible client | | [CLI Reference](docs/cli.md) | Every command, flag, and example in one place | | [Go Library](docs/library.md) | Embed sand in your own Go programs | | [Contributing](CONTRIBUTING.md) | How to build, test, and submit changes | ## License Apache-2.0 (see `LICENSE`).