gantry

module

v0.0.21 Latest Latest Go to latest Published: Sep 6, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ejpir/gantry

Links

Open Source Insights

README ¶

Gantry

Gantry runs OCI images in lightweight Linux microVMs. It is a standalone Go VMM and CLI; Docker, containerd, QEMU, and libkrun are not required.

It uses KVM on Linux, Hypervisor.framework on Apple silicon, and WHPX on Windows.

Gantry is experimental. Linux and Apple silicon macOS are supported. Windows support is experimental.

Install

Download the binary for your host from the latest release.

Linux

# Use amd64 or arm64 as appropriate.
curl -L https://github.com/ejpir/gantry/releases/latest/download/gantry-linux-amd64 -o gantry
chmod +x gantry

macOS (Apple silicon)

curl -L https://github.com/ejpir/gantry/releases/latest/download/gantry-darwin-arm64 -o gantry
chmod +x gantry
xattr -d com.apple.quarantine gantry

Windows (x86-64)

Invoke-WebRequest https://github.com/ejpir/gantry/releases/latest/download/gantry-windows-amd64.exe -OutFile gantry.exe

The first sandbox start downloads and verifies the matching guest kernel, root filesystem, and default image.

Quick start

Run a disposable container in a fresh VM:

./gantry exec -image alpine:latest -- /bin/sh

Create and reuse a named sandbox:

./gantry start dev -image debian:bookworm-slim
./gantry exec dev -- /bin/bash
./gantry stop dev
./gantry resume dev
./gantry delete dev

Open the terminal dashboard:

./gantry tui

Highlights

OCI registry images, layouts, archives, Docker saves, and EROFS images
Persistent sandboxes with configurable CPU, memory, disk, and runtime
crun by default, with optional in-VM gVisor (-runtime runsc)
Host shares, egress policy, proxy routing, traffic inspection, and ports
Local SSH and an optional in-VM IDE container for VS Code Dev Containers
In-memory secrets, OAuth custody, and a credential-injecting MCP gateway
Terminal dashboard and local HTTP/JSON manager API

See the Gantry manual for usage, configuration, networking, credentials, architecture, and the security model. Run gantry --help for the complete CLI reference.

Platforms

Host	Backend	Status
Linux arm64	KVM	Supported; requires `/dev/kvm`
Linux x86-64	KVM	Supported; verified on EC2 `c5.metal`
macOS arm64	Hypervisor.framework	Supported on macOS 13+
Windows x86-64	WHPX	Experimental; verified on EC2 `m6i.metal`

Startup performance

Measured cold-guest startup to RPC readiness with warm host file caches:

Host	Backend	Configuration	Observed startup
Linux arm64	KVM	1 vCPU, 512 MiB, network off	72.9 ms median CLI-to-ready
macOS arm64	Hypervisor.framework	1 vCPU, 512 MiB, network off	94.1 ms median CLI-to-ready
Linux x86-64	KVM	1 vCPU, 512 MiB, network off	177.8 ms median CLI-to-ready
Windows x86-64	WHPX	1 vCPU, 512 MiB, split VMM worker	approximately 400 ms daemon-to-ready (371–446 ms observed)

Linux and macOS report full CLI latency. The experimental Windows result is a native WHPX daemon-to-ready range. See scripts/bench-boot-scaling.sh and scripts/aws-whpx to reproduce these measurements.

Isolation and limitations

Each sandbox runs in its own VM. The trusted supervisor runs as the user who launched Gantry. In the default auto mode, guest-facing work is split into confined workers where the host supports it:

Linux uses namespaces, capability removal, Landlock, and seccomp.
macOS uses role-specific Seatbelt profiles.
Windows uses one-process Jobs and AppContainers: VMM device emulation and MCP run without network capabilities, while networking uses a separate worker with an exact capability set. A narrow Job-confined broker owns the WHPX partition because WHPX cannot run inside the zero-capability AppContainer.

Workers actively verify their filesystem, network, and process restrictions. Use -process-isolation=required to fail startup unless the full required boundary is established. On Windows, required mode rejects host-loopback access and published ports rather than weakening AppContainer isolation.

Gantry is not yet a hardened boundary for hostile public multi-tenancy. Snapshots and rollback are not supported; use gantry export on a stopped sandbox for a portable OCI archive. Writable layers are mutable and may be attached to only one running VM at a time.

See Security for the complete threat model and platform-specific limits.

Updates

Tagged builds check for stable releases in the background. Update explicitly with:

./gantry update

Release binaries and guest assets are SHA-256 verified. Release artifacts also include Sigstore build provenance.

Build from source

Go 1.26.6 or newer is required.

go install github.com/ejpir/gantry/cmd/gantry@latest

# Or from a checkout:
./scripts/build.sh
./scripts/mkimage.sh alpine:latest artifacts/alpine.erofs
./scripts/mkkernel.sh
go test ./...

Set GANTRY_ARTIFACTS to use an explicit guest-asset directory.

Security

Report vulnerabilities privately as described in SECURITY.md. Do not open public issues for sandbox-boundary vulnerabilities.

Acknowledgements

containerd/nerdbox · gvisor-tap-vsock · go-erofs · go-fuse · gVisor

Gantry is licensed under Apache-2.0. Vendored code in third_party/ retains its original license.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
managerapi Package managerapi publishes the Gantry manager's versioned OpenAPI contract.	Package managerapi publishes the Gantry manager's versioned OpenAPI contract.
services/system/v1 Package system defines the system service.	Package system defines the system service.
cmd
gantry command
gantry-guest command Command gantry-guest is the multicall guest-side helper binary: one static Linux executable dispatched by argv[0] (busybox-style) or by its first argument.	Command gantry-guest is the multicall guest-side helper binary: one static Linux executable dispatched by argv[0] (busybox-style) or by its first argument.
hostctl command hostctl — ttrpc client for the nerdbox guest agent (vminitd) running inside a gantry VM.	hostctl — ttrpc client for the nerdbox guest agent (vminitd) running inside a gantry VM.
guest
crunshim command crunshim is installed as /sbin/crun in the gVisor rootfs variant (mkrootfs-gvisor.sh).	crunshim is installed as /sbin/crun in the gVisor rootfs variant (mkrootfs-gvisor.sh).
init command Guest PID 1 for gantry — a static aarch64 Go binary, like nerdbox's vminitd but minimal: mount filesystems, say hello, run a shell on the serial console, then power off via PSCI (which our VMM turns into a clean exit).	Guest PID 1 for gantry — a static aarch64 Go binary, like nerdbox's vminitd but minimal: mount filesystems, say hello, run a shell on the serial console, then power off via PSCI (which our VMM turns into a clean exit).
internal
atomicfile Package atomicfile replaces small files without exposing partial contents.	Package atomicfile replaces small files without exposing partial contents.
client Package client implements the host-side ttrpc and stream control plane for vminitd inside a gantry guest.	Package client implements the host-side ttrpc and stream control plane for vminitd inside a gantry guest.
dashboard
dashboard/api Package api defines the data and operations consumed by the local dashboard.	Package api defines the data and operations consumed by the local dashboard.
ext4view Package ext4view exposes a read-only, journal-replayed view of an ext4 filesystem to go-diskfs.	Package ext4view exposes a read-only, journal-replayed view of an ext4 filesystem to go-diskfs.
fusewire Package fusewire defines the raw FUSE request boundary shared by the host filesystem service, broker transport, and virtio frontend.	Package fusewire defines the raw FUSE request boundary shared by the host filesystem service, broker transport, and virtio frontend.
guestasset Package guestasset locates and stages the host-side artifacts used to boot guests.	Package guestasset locates and stages the host-side artifacts used to boot guests.
gutil Package gutil holds the tiny helpers shared by gantry's internal packages.	Package gutil holds the tiny helpers shared by gantry's internal packages.
image Package image loads OCI images into flattened EROFS disks and keeps the image config (env, entrypoint, user, workdir) that used to be thrown away.	Package image loads OCI images into flattened EROFS disks and keeps the image config (env, entrypoint, user, workdir) that used to be thrown away.
image/auth Package auth resolves registry credentials without ever implementing a keychain: GANTRY_REGISTRY_AUTH, gantry's own credentials.json, Docker's config (helpers and plaintext), Podman's auth files, then anonymous — first hit wins.	Package auth resolves registry credentials without ever implementing a keychain: GANTRY_REGISTRY_AUTH, gantry's own credentials.json, Docker's config (helpers and plaintext), Podman's auth files, then anonymous — first hit wins.
mcpspec Package mcpspec owns the persisted grammar for remote MCP servers.	Package mcpspec owns the persisted grammar for remote MCP servers.
mcpworker Package mcpworker owns the untrusted _mcp-worker runtime and the bounded stream/capability protocol it shares with the trusted supervisor half.	Package mcpworker owns the untrusted _mcp-worker runtime and the bounded stream/capability protocol it shares with the trusted supervisor half.
netpol Package netpol enforces an egress network policy on sandbox traffic.	Package netpol enforces an egress network policy on sandbox traffic.
networkworker Package networkworker owns the untrusted _net-worker child runtime and its private control protocol.	Package networkworker owns the untrusted _net-worker child runtime and its private control protocol.
packetcapture Package packetcapture records a bounded, memory-only view of virtual Ethernet frames.	Package packetcapture records a bounded, memory-only view of virtual Ethernet frames.
sandbox
sandbox/boundedlog Package boundedlog is the bounded log pipe: an os.Pipe whose read end is drained at a capped rate into a size-bounded, self-compacting file.	Package boundedlog is the bounded log pipe: an os.Pipe whose read end is drained at a capped rate into a size-bounded, self-compacting file.
sandbox/cliout Package cliout holds the presentation policy shared by gantry's command output.	Package cliout holds the presentation policy shared by gantry's command output.
sandbox/config Package config contains persisted sandbox settings and typed launch inputs.	Package config contains persisted sandbox settings and typed launch inputs.
sandbox/control
sandbox/controlcmd Package controlcmd is the client half of the sandbox control plane: the `gantry share`, `gantry port`, `gantry net-policy` and resource commands, plus the calls the dashboard makes on their behalf.	Package controlcmd is the client half of the sandbox control plane: the `gantry share`, `gantry port`, `gantry net-policy` and resource commands, plus the calls the dashboard makes on their behalf.
sandbox/controlproto Package controlproto is the wire contract for a sandbox's ctl.sock: the request and response frames, the session sub-protocol, and the bounded framing both ends must agree on.	Package controlproto is the wire contract for a sandbox's ctl.sock: the request and response frames, the session sub-protocol, and the bounded framing both ends must agree on.
sandbox/credhelper Package credhelper implements the host side of the credential broker: a bounded JSON protocol served on a per-sandbox unix socket that the VMM's vsock device reaches when a guest process connects to the broker port (guest connect to vsock port Port → VMM dials <sandboxDir>/SockName).	Package credhelper implements the host side of the credential broker: a bounded JSON protocol served on a per-sandbox unix socket that the VMM's vsock device reaches when a guest process connects to the broker port (guest connect to vsock port Port → VMM dials <sandboxDir>/SockName).
sandbox/credhelper/credproto Package credproto defines the wire format between the guest credential helper (cmd/gantry-guest) and the host broker (internal/sandbox/credhelper): one JSON request line, one JSON response line, over the vsock channel the VMM bridges to <sandboxDir>/SockName.	Package credproto defines the wire format between the guest credential helper (cmd/gantry-guest) and the host broker (internal/sandbox/credhelper): one JSON request line, one JSON response line, over the vsock channel the VMM bridges to <sandboxDir>/SockName.
sandbox/dashboardsvc
sandbox/devcontainers
sandbox/importer
sandbox/inspection Package inspection provides the common read model for sandbox frontends.	Package inspection provides the common read model for sandbox frontends.
sandbox/layout Package layout owns the on-disk layout of the gantry sandbox home and the liveness checks that go with it: where a sandbox's state directory lives, which names are legal inside it, and whether the daemon that owns it is still running.	Package layout owns the on-disk layout of the gantry sandbox home and the liveness checks that go with it: where a sandbox's state directory lives, which names are legal inside it, and whether the daemon that owns it is still running.
sandbox/lifecycle Package lifecycle defines the application contract shared by Gantry's command-line, dashboard, and HTTP adapters.	Package lifecycle defines the application contract shared by Gantry's command-line, dashboard, and HTTP adapters.
sandbox/localsec Package localsec keeps gantry's local endpoints and state directories reachable only by the user who owns them: restrictive modes on Unix, explicit private DACLs on Windows, and peer-credential checks on the unix sockets the daemon and manager listen on.	Package localsec keeps gantry's local endpoints and state directories reachable only by the user who owns them: restrictive modes on Unix, explicit private DACLs on Windows, and peer-credential checks on the unix sockets the daemon and manager listen on.
sandbox/manager
sandbox/mcpgw Package mcpgw implements the per-sandbox MCP gateway (docs/mcp-gateway.md): the guest agent speaks newline-delimited JSON-RPC (MCP stdio framing) over one vsock-bridged connection, and the gateway fans tool calls out to upstream servers — for milestone 1, local stdio servers spawned guest-side through the daemon's exec channel.	Package mcpgw implements the per-sandbox MCP gateway (docs/mcp-gateway.md): the guest agent speaks newline-delimited JSON-RPC (MCP stdio framing) over one vsock-bridged connection, and the gateway fans tool calls out to upstream servers — for milestone 1, local stdio servers spawned guest-side through the daemon's exec channel.
sandbox/mcpgw/mcpproto Package mcpproto holds the wire constants for the per-sandbox MCP gateway channel (docs/mcp-gateway.md): the guest connects to vsock VsockPort, the VMM bridges the connection to <sandboxDir>/SockName where the daemon's gateway accepts it.	Package mcpproto holds the wire constants for the per-sandbox MCP gateway channel (docs/mcp-gateway.md): the guest connects to vsock VsockPort, the VMM bridges the connection to <sandboxDir>/SockName where the daemon's gateway accepts it.
sandbox/mcpworker Package mcpworker is the trusted supervisor half of the split MCP gateway.	Package mcpworker is the trusted supervisor half of the split MCP gateway.
sandbox/networker
sandbox/oauthbridge Package oauthbridge runs the host-side OAuth loopback callback bridge for a sandbox.	Package oauthbridge runs the host-side OAuth loopback callback bridge for a sandbox.
sandbox/oauthtokens Package oauthtokens is the host-side custody registry for OAuth token sets (docs/credential-brokering.md workstream 3).	Package oauthtokens is the host-side custody registry for OAuth token sets (docs/credential-brokering.md workstream 3).
sandbox/rwlayer
sandbox/sshgw Package sshgw terminates SSH inside the trusted Gantry daemon.	Package sshgw terminates SSH inside the trusted Gantry daemon.
sandbox/vmmworker
sandbox/worker Package worker is the substrate the split child processes are built on: a process-neutral launch and lifecycle harness, the confinement and handle-passing primitives each platform needs, and empty-by-default explicit role environments.	Package worker is the substrate the split child processes are built on: a process-neutral launch and lifecycle harness, the confinement and handle-passing primitives each platform needs, and empty-by-default explicit role environments.
sandbox/worker/workertest Package workertest holds the assertions a re-exec'd worker makes about itself from inside the child process.	Package workertest holds the assertions a re-exec'd worker makes about itself from inside the child process.
secret Package secret holds workload secrets: values injected INTO the guest for the agent to use.	Package secret holds workload secrets: values injected INTO the guest for the agent to use.
selfupdate Package selfupdate discovers Gantry releases and installs a verified platform binary over the currently running executable.	Package selfupdate discovers Gantry releases and installs a verified platform binary over the currently running executable.
sharebroker Package sharebroker carries bounded raw FUSE requests between a virtio-fs frontend and a host-side request handler.	Package sharebroker carries bounded raw FUSE requests between a virtio-fs frontend and a host-side request handler.
sharefs Package sharefs owns host filesystem capabilities, export policy, and the dynamic FUSE namespace used for sandbox directory sharing.	Package sharefs owns host filesystem capabilities, export policy, and the dynamic FUSE namespace used for sandbox directory sharing.
shares Package shares defines host-directory export specifications and the virtio-fs manifest shared by the CLI, sandbox control plane, VMM assembly, and guest session client.	Package shares defines host-directory export specifications and the virtio-fs manifest shared by the CLI, sandbox control plane, VMM assembly, and guest session client.
spikecheck command spikecheck runs inside a container whose rootfs is a virtio-fs hub export (docs/kubernetes-runtimeclass.md, Phase K0 dynamic-rootfs spike).	spikecheck runs inside a container whose rootfs is a virtio-fs hub export (docs/kubernetes-runtimeclass.md, Phase K0 dynamic-rootfs spike).
sshpolicy Package sshpolicy contains SSH forwarding policy shared by the host gateway and the in-guest relay.	Package sshpolicy contains SSH forwarding policy shared by the host gateway and the in-guest relay.
virtio
vmm Package vmm boots and runs a guest virtual machine on the host's native hypervisor.	Package vmm boots and runs a guest virtual machine on the host's native hypervisor.
vmm/boot Package boot builds what a guest boots from: the x86 boot protocol setup (zero page, e820 map, MP tables, vmlinux ELF load) and the arm64 flattened device tree.	Package boot builds what a guest boots from: the x86 boot protocol setup (zero page, e820 map, MP tables, vmlinux ELF load) and the arm64 flattened device tree.
vmm/devices
vmmworker Package vmmworker runs the untrusted VMM child process.	Package vmmworker runs the untrusted VMM child process.
vnet Package vnet embeds gvisor-tap-vsock's virtual network stack in-process: gateway, DHCP, DNS, and NAT via gVisor netstack — everything the external gvproxy subprocess provided, with no binary to ship or port to babysit.	Package vnet embeds gvisor-tap-vsock's virtual network stack in-process: gateway, DHCP, DNS, and NAT via gVisor netstack — everything the external gvproxy subprocess provided, with no binary to ship or port to babysit.
vsockports Package vsockports defines the host services a guest may reach over vsock.	Package vsockports defines the host services a guest may reach over vsock.
workerconf Package workerconf confines a re-executed worker process after it has consumed its descriptor table and before it opens the hypervisor.	Package workerconf confines a re-executed worker process after it has consumed its descriptor table and before it opens the hypervisor.
workerproto Package workerproto implements the private, versioned wire protocol between a gantry supervisor and its re-executed workers.	Package workerproto implements the private, versioned wire protocol between a gantry supervisor and its re-executed workers.
tests
e2e/managerapi command managerapi is a black-box lifecycle test for `gantry serve`.	managerapi is a black-box lifecycle test for `gantry serve`.
tools
mkinitramfs command mkinitramfs builds a gzip'd newc-format cpio initramfs — no external tools needed.	mkinitramfs builds a gzip'd newc-format cpio initramfs — no external tools needed.