README
¶
Fuse
Sandboxed microVMs on your own hosts, driven by an API.
Fuse is a control plane for Firecracker and QEMU microVMs. Register your hosts, describe a
workload in a Fusefile, and Fuse schedules it, boots the VM, and tracks the whole lifecycle
(provision, running, drain, destroy) with snapshots, fork, exec, live event streams, and
Prometheus metrics. CPU workloads run on Firecracker; GPU workloads run on QEMU hosts with
whole cards or MIG slices.
You bring the hosts. State lives in Postgres and on your disks, nowhere else.
Install
brew install --cask folsomintel/fuse/fuse
Or without Homebrew, on macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/folsomintel/fuse/main/ops/install-fuse.sh | bash
The script verifies the release archive against the release's checksums.txt before
installing, and puts the binary in /usr/local/bin (or ~/.local/bin if that is not
writable). Set VERSION=vX.Y.Z to pin a release, FUSE_INSTALL_DIR to choose where.
Upgrade with brew upgrade --cask fuse, check with fuse --version. You can also build
from a checkout with go build -o bin/fuse ./cli. Mind the naming: the fuse_* archives
are the orchestrator, fuse-cli_* is the CLI.
First run
The CLI is only a client. You need an orchestrator reachable over HTTP and at least one host
agent running before it can do anything. sudo ./fc-agent.sh bootstrap in
host-agent/ brings both up on a single machine.
fuse quickstart # connect an orchestrator, register a host
fuse init # scaffold a Fusefile
fuse validate # check it offline, without creating anything
fuse up --secret pg_password=devpassword
fuse environment list
fuse environment exec <id> -- echo hello
fuse environment fork <id>
quickstart needs a tty. Headless, run the two commands it wraps:
fuse connect https://orch.example.com --token "$ORCH_AUTH_TOKEN"
fuse host register prod-east-1 --url http://10.0.0.5:8090 --token "$FC_AGENT_TOKEN" --max-vms 20
Docs
- Quickstart, the steps above with the detail
- Fusefile, the YAML
fuse upcompiles - Guides, agent sandboxes, CI runners, GPU workloads, interactive debugging
- Self-hosting, orchestrator deploy plus Firecracker and GPU host setup
- CLI reference, every command, flag, and context
- REST API, the OpenAPI spec the docs site renders
- SDKs, Go (
sdks/go), Python (folsom-fuse), TypeScript (@folsom/fuse)
Contributing
Go 1.26 monorepo, no Makefile. Most tests run against in-memory stubs, so you need neither VMs nor Postgres to work on it.
gofmt -l . # must print nothing
go vet ./...
go build ./...
go test ./... -race -count=1
golangci-lint run ./... # pinned to v2.12.2 in ci
License
MIT, see LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
config
package config manages the local cli state: orchestrator contexts (base url + token) and the per-context active host.
|
package config manages the local cli state: orchestrator contexts (base url + token) and the per-context active host. |
|
Command fused is the reference in-guest agent for Fuse.
|
Command fused is the reference in-guest agent for Fuse. |
|
Package hostagent exposes the host-agent assets the fuse cli embeds for `fuse local`: the firecracker agent and the local-stack setup script.
|
Package hostagent exposes the host-agent assets the fuse cli embeds for `fuse local`: the firecracker agent and the local-stack setup script. |
|
internal
|
|
|
api
Package api is the HTTP (REST) surface of the orchestrator.
|
Package api is the HTTP (REST) surface of the orchestrator. |
|
firecracker
Package firecracker implements a Firecracker-based Provider.
|
Package firecracker implements a Firecracker-based Provider. |
|
fusefile
package fusefile is the canonical authoring format for a fuse environment.
|
package fusefile is the canonical authoring format for a fuse environment. |
|
hostwire
Package hostwire holds the pieces of the orchestrator-to-host-agent wire that both the firecracker and qemu providers speak.
|
Package hostwire holds the pieces of the orchestrator-to-host-agent wire that both the firecracker and qemu providers speak. |
|
orchestrator
Package orchestrator defines the interface for sandbox providers and implements the boot flow that provisions or restores environments.
|
Package orchestrator defines the interface for sandbox providers and implements the boot flow that provisions or restores environments. |
|
qemu
Package qemu implements a QEMU/KVM-based Provider for GPU passthrough environments.
|
Package qemu implements a QEMU/KVM-based Provider for GPU passthrough environments. |
|
Command orchestrator runs the Fuse orchestrator REST API.
|
Command orchestrator runs the Fuse orchestrator REST API. |
|
sdks
|
|
|
go
module
|
|
|
tests
|
|
|
e2e
Package e2e holds end-to-end "deploy everything" tests for Fuse.
|
Package e2e holds end-to-end "deploy everything" tests for Fuse. |