masterblaster

command module

v0.1.1 Latest Latest Go to latest Published: Mar 6, 2026 License: AGPL-3.0 Imports: 16 Imported by: 0

Details

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

Repository

github.com/papercomputeco/masterblaster

Links

Open Source Insights

README ¶

Masterblaster - `mb`

Create, manage, and orchestrate AI agents sandboxes.

Masterblaster boots stereOS machines - a NixOS-based Linux distribution purpose-built for AI agents - and manages their full lifecycle: image pulling, machine creation, secret injection, shared directory mounting, and agent orchestration.

Sandboxes are ephemeral, isolated, reproducible, and focused on security.

Install

curl -fsSL https://mb.stereos.ai/latest/install.sh | bash

Quick start

1. Pull a mixtape

Mixtapes are pre-built stereOS images bundled with AI agent harnesses. Pull one from the registry:

mb pull opencode-mixtape

2. Create a jcard

A jcard.toml file defines your sandbox configuration. Run mb init to generate one, or create it by hand:

# jcard.toml

mixtape = "opencode-mixtape:latest"

[resources]
cpus   = 1
memory = "4GiB"
disk   = "40GiB"

[network]
mode = "nat"

[[shared]]
host  = "./"
guest = "/home/agent/workspace"

[secrets]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"

[agent]
harness = "opencode"
prompt  = "review the code in this directory and fix any failing tests"
workdir = "/home/agent/workspace"
restart = "on-failure"

3. Launch

mb up            # Create sandbox from jcard.tomlmb ssh my-sandbox
mb ssh           # SSH into a running sandbox
mb list          # List all sandboxes
mb status        # Check sandbox status
mb down          # Graceful shutdown
mb destroy       # Remove sandbox and all resources

jcard.toml reference

The jcard is the single configuration file for a sandbox. Most fields are optional and defaults are applied automatically.

Section	Field	Default	Description
(top)	`mixtape`	`"base:latest"`	Mixtape image in `name:tag` format
(top)	`mixtape_digest`		Pin to an exact OCI digest
(top)	`name`	parent directory name	Unique sandbox name
`[resources]`	`cpus`	`2`	Virtual CPUs
`[resources]`	`memory`	`"4GiB"`	RAM (KiB, MiB, GiB)
`[resources]`	`disk`	`"20GiB"`	Root disk size
`[network]`	`mode`	`"nat"`	`"nat"`, `"bridged"`, or `"none"`
`[network]`	`forwards`		Port forwards: `[{ host, guest, proto }]`
`[network]`	`egress_allow`		Domain/CIDR allowlist for outbound traffic
`[[shared]]`	`host`		Host directory path
`[[shared]]`	`guest`		Guest mount point
`[[shared]]`	`readonly`	`false`	Prevent agent from modifying host files
`[secrets]`	key = value		Injected to tmpfs via stereosd (never on disk)
`[agent]`	`harness`	`"claude-code"`	`"claude-code"`, `"opencode"`, `"gemini-cli"`, `"custom"`
`[agent]`	`prompt`		Prompt given to the agent on boot
`[agent]`	`prompt_file`		Path to a prompt file (relative to jcard.toml)
`[agent]`	`workdir`	first `[[shared]]` guest path or `"/workspace"`	Agent working directory
`[agent]`	`restart`	`"no"`	`"no"`, `"on-failure"`, `"always"`
`[agent]`	`max_restarts`	`0` (unlimited)	Max restart attempts
`[agent]`	`timeout`		Agent timeout (e.g. `"2h"`)
`[agent]`	`grace_period`	`"30s"`	SIGTERM grace period before SIGKILL
`[agent]`	`env`		Environment variables for the agent process

Use ${ENV_VAR} syntax in [secrets], [agent.env], and path fields to reference host environment variables. Paths support ~ expansion.

CLI commands

mb pull <name[:tag]>       Pull a mixtape from the registry
mb init                    Generate a jcard.toml
mb up [--config <path>]    Create and start a sandbox
mb down [name] [--force]   Stop a running sandbox
mb status [name]           Show sandbox status
mb destroy [name] [--yes]  Remove sandbox and all resources
mb ssh [name] [-u user]    SSH into a sandbox (default user: admin)
mb list                    List all sandboxes
mb mixtapes ls             List locally available mixtapes
mb version                 Display version info
mb serve                   Start the daemon (auto-started by mb up)

Global flags: --config-dir <path>, --verbose

Backends

Backend	Platform	Accelerator	Control plane	Notes
QEMU	macOS/Apple Silicon	HVF	TCP (user-mode net)	Default backend
QEMU	Linux/aarch64	KVM	vsock (`vhost-vsock-pci`)	Native vsock, `io_uring` disk I/O
Apple Virt	macOS/Apple Silicon	Vz.framework	virtio-socket	`MB_BACKEND=applevirt`, requires codesigning

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

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

Path	Synopsis
cmd
destroy Package destroycmder provides the destroy command for removing a sandbox and all its on-disk resources.	Package destroycmder provides the destroy command for removing a sandbox and all its on-disk resources.
down Package downcmder provides the down command for gracefully stopping a running sandbox.	Package downcmder provides the down command for gracefully stopping a running sandbox.
init Package initcmder provides the init command for creating a jcard.toml configuration file in the current directory.	Package initcmder provides the init command for creating a jcard.toml configuration file in the current directory.
list Package listcmder provides the list command for showing all known sandbox instances.	Package listcmder provides the list command for showing all known sandbox instances.
mixtapes Package mixtapescmder provides the mixtapes command group for managing StereOS mixtape images, both locally and in the OCI registry.	Package mixtapescmder provides the mixtapes command group for managing StereOS mixtape images, both locally and in the OCI registry.
pull Package pullcmder provides the top-level "mb pull" command for downloading StereOS mixtape images from an OCI registry.	Package pullcmder provides the top-level "mb pull" command for downloading StereOS mixtape images from an OCI registry.
serve Package servecmder provides the serve command for starting the Masterblaster daemon.	Package servecmder provides the serve command for starting the Masterblaster daemon.
ssh Package sshcmder provides the ssh command for connecting to a running sandbox via SSH.	Package sshcmder provides the ssh command for connecting to a running sandbox via SSH.
status Package statuscmder provides the status command for displaying the current state of a sandbox.	Package statuscmder provides the status command for displaying the current state of a sandbox.
up Package upcmder provides the up command for creating and starting a StereOS sandbox VM.	Package upcmder provides the up command for creating and starting a StereOS sandbox VM.
version Package versioncmder provides the "version" spf13/cobra command which prints the version, buildtime, and sha of the build.	Package versioncmder provides the "version" spf13/cobra command which prints the version, buildtime, and sha of the build.
vmhost Package vmhostcmder provides the hidden vmhost subcommand that manages a single VM's lifecycle.	Package vmhostcmder provides the hidden vmhost subcommand that manages a single VM's lifecycle.
pkg
config Package config handles parsing and validation of jcard.toml configuration files.	Package config handles parsing and validation of jcard.toml configuration files.
daemon Package daemon implements the long-lived Masterblaster daemon service.	Package daemon implements the long-lived Masterblaster daemon service.
daemon/client Package client provides a thin wrapper for CLI commands to communicate with the Masterblaster daemon over the unix domain socket.	Package client provides a thin wrapper for CLI commands to communicate with the Masterblaster daemon over the unix domain socket.
mbconfig Package mbconfig centralizes Masterblaster configuration using Viper.	Package mbconfig centralizes Masterblaster configuration using Viper.
mixtapes Package mixtapes manages StereOS mixtape images -- the bootable VM images that contain pre-configured agentic workflows.	Package mixtapes manages StereOS mixtape images -- the bootable VM images that contain pre-configured agentic workflows.
ssh Package ssh provides SSH connectivity to StereOS sandbox VMs.	Package ssh provides SSH connectivity to StereOS sandbox VMs.
ui Package ui provides terminal output helpers styled with charmbracelet/lipgloss.	Package ui provides terminal output helpers styled with charmbracelet/lipgloss.
utils Package utils provides bespoke, one off utils that don't make sense to be their own package	Package utils provides bespoke, one off utils that don't make sense to be their own package
vm Package vm provides VM lifecycle management including the Backend interface abstraction, instance types, state persistence, and QMP communication.	Package vm provides VM lifecycle management including the Backend interface abstraction, instance types, state persistence, and QMP communication.
vmhost Package vmhost implements the control protocol between the mb daemon and per-VM vmhost child processes.	Package vmhost implements the control protocol between the mb daemon and per-VM vmhost child processes.
vsock Package vsock implements the host-side client for communicating with stereosd inside a StereOS guest VM over the vsock control plane.	Package vsock implements the host-side client for communicating with stereosd inside a StereOS guest VM over the vsock control plane.