config

Documentation

Overview

Package config handles parsing and validation of jcard.toml configuration files. The jcard.toml format is the primary configuration mechanism for Masterblaster sandboxes, defining the mixtape, resources, networking, shared directories, secrets, and agent configuration.

Index

• func DefaultJcardTOML() string
• func Marshal(cfg *JcardConfig) ([]byte, error)
• type AgentConfig
• type AgentType
• type JcardConfig
  • func DefaultJcard() *JcardConfig
  • func Load(path string) (*JcardConfig, error)
• type NetworkConfig
• type PortForward
• type ResourcesConfig
• type SharedMount

Functions

func DefaultJcardTOML

func DefaultJcardTOML() string

DefaultJcardTOML returns a well-commented default jcard.toml suitable for scaffolding with `mb init`.

func Marshal

func Marshal(cfg *JcardConfig) ([]byte, error)

Marshal serializes a JcardConfig to TOML format.

Types

type AgentConfig

type AgentConfig struct {
	// Type selects the agent execution mode.
	// "sandboxed" (default) runs in a gVisor container with /nix/store sharing.
	// "native" runs directly on the host in a tmux session.
	Type AgentType `toml:"type,omitempty"`

	// Name is a unique identifier for this agent. If omitted, a name is
	// auto-generated from the harness name (e.g. "claude-code", "claude-code-1").
	Name string `toml:"name"`

	// Harness is the agent harness to use: "claude-code", "opencode",
	// "gemini-cli", or "custom".
	Harness string `toml:"harness"`

	// Prompt is the prompt or command to give the agent on boot.
	Prompt string `toml:"prompt"`

	// PromptFile is a path to a prompt file (relative to jcard.toml).
	// Takes precedence over Prompt.
	PromptFile string `toml:"prompt_file"`

	// Workdir is the working directory inside the sandbox.
	// Defaults to the first shared mount guest path, or /workspace.
	Workdir string `toml:"workdir"`

	// Restart policy: "no" (default), "on-failure", "always".
	Restart string `toml:"restart"`

	// MaxRestarts is the maximum restart attempts (0 = unlimited).
	MaxRestarts int `toml:"max_restarts"`

	// Timeout for the agent to complete (Go duration string, e.g. "2h").
	Timeout string `toml:"timeout"`

	// GracePeriod for SIGTERM before SIGKILL (Go duration, default "30s").
	GracePeriod string `toml:"grace_period"`

	// Session is the tmux session name. Defaults to the harness name.
	// Only used for native agents.
	Session string `toml:"session"`

	// ExtraPackages is a list of additional Nix package attribute names
	// to install into the sandbox (e.g. ["ripgrep", "fd", "python311"]).
	// These are resolved against the system's nixpkgs and materialized
	// into /nix/store at agent launch time. Only used for sandboxed agents.
	ExtraPackages []string `toml:"extra_packages,omitempty"`

	// Replicas is the number of identical agents to launch from this
	// spec. Defaults to 1. When > 1, each replica gets a unique name
	// suffixed with its index (e.g. "reviewer-0", "reviewer-1").
	// Useful for launching swarms of agents performing the same task.
	Replicas int `toml:"replicas"`

	// Env are environment variables set only for the agent process.
	Env map[string]string `toml:"env"`
}

AgentConfig defines what agent harness to run and how agentd manages it. This section is passed through to agentd on the guest.

type AgentType

type AgentType string

AgentType defines how the agent process is executed inside the guest.

const (
	// AgentTypeSandboxed runs the agent in a gVisor (runsc) sandbox with
	// read-only /nix/store bind mounts. This is the default.
	AgentTypeSandboxed AgentType = "sandboxed"

	// AgentTypeNative runs the agent directly on the host in a tmux
	// session as the agent user (the original agentd behavior).
	AgentTypeNative AgentType = "native"
)

type JcardConfig

type JcardConfig struct {
	// Mixtape is the StereOS image to boot, in "name:tag" format.
	// The tag defaults to "latest" when omitted.
	//
	// Examples:
	//   "opencode-mixtape"       -> opencode-mixtape:latest
	//   "opencode-mixtape:0.1.0" -> pinned to tag 0.1.0
	//   "base"                   -> base:latest
	//
	// Images are resolved from ~/.config/mb/mixtapes/{name}/{tag}/.
	// Pull with: mb pull opencode-mixtape:0.1.0
	Mixtape string `toml:"mixtape"`

	// MixtapeDigest pins to an exact digest for reproducible builds.
	// When set, takes precedence over the tag in Mixtape.
	MixtapeDigest string `toml:"mixtape_digest"`

	// Name is a human-readable name for this sandbox. Defaults to the
	// parent directory name. Must be unique across running sandboxes.
	Name string `toml:"name"`

	// Resources for the sandbox VM.
	Resources ResourcesConfig `toml:"resources"`

	// Network configuration for the sandbox.
	Network NetworkConfig `toml:"network"`

	// Shared directories mounted from host into sandbox.
	Shared []SharedMount `toml:"shared"`

	// Secrets injected into the sandbox at runtime via stereosd.
	Secrets map[string]string `toml:"secrets"`

	// Agents defines the agent harnesses to run inside this sandbox.
	// Each entry is an independent agent managed by agentd.
	Agents []AgentConfig `toml:"agents"`
}

JcardConfig is the top-level configuration parsed from a jcard.toml file.

func DefaultJcard

func DefaultJcard() *JcardConfig

DefaultJcard returns a default jcard.toml configuration suitable for scaffolding with `mb init`.

func Load

func Load(path string) (*JcardConfig, error)

Load reads and parses a jcard.toml config file, applies defaults, expands environment variables and paths, and validates the result.

type NetworkConfig

type NetworkConfig struct {
	// Mode is the network mode: "nat" (default), "bridged", or "none".
	Mode string `toml:"mode"`

	// Forwards are port forwards from host to sandbox (nat mode only).
	Forwards []PortForward `toml:"forwards"`

	// EgressAllow is an allowlist of domains/CIDRs reachable from the
	// sandbox. Empty means no restrictions.
	EgressAllow []string `toml:"egress_allow"`
}

NetworkConfig describes sandbox networking.

type PortForward

type PortForward struct {
	Host  int    `toml:"host"`
	Guest int    `toml:"guest"`
	Proto string `toml:"proto"` // "tcp" or "udp"
}

PortForward maps a host port to a guest port.

type ResourcesConfig

type ResourcesConfig struct {
	CPUs   int    `toml:"cpus"`
	Memory string `toml:"memory"`
	Disk   string `toml:"disk"`
}

ResourcesConfig describes the VM resource allocation.

type SharedMount

type SharedMount struct {
	Host     string `toml:"host"`
	Guest    string `toml:"guest"`
	ReadOnly bool   `toml:"readonly"`
}

SharedMount maps a host directory to a guest mount point.