jcard.toml

The jcard.toml tells mb which mixtape to boot and which agents to run.

Minimal example

mixtape = "opencode-mixtape:latest"

[[agents]]
harness = "opencode"
prompt = "Hello world!"

Top-level fields

Field	Type	Required	Description
`mixtape`	string	yes	Mixtape image and tag to boot.

[[agents]] section

Multiple agents can run concurrently inside a single sandbox. Each [[agents]] entry defines an independent agent managed by agentd.

Field	Type	Default	Description
`name`	string	auto-generated	Unique identifier for this agent. If omitted, auto-generated from harness (e.g. `"claude-code"`, `"claude-code-1"`).
`harness`	string	—	Agent runner: `"claude-code"`, `"opencode"`, `"gemini-cli"`, or `"custom"`. Required.
`type`	string	`"sandboxed"`	Execution mode: `"sandboxed"` (gVisor container) or `"native"` (tmux session).
`prompt`	string	`""`	Prompt passed to the agent at startup. Empty starts interactive mode.
`prompt_file`	string	—	Path to a prompt file inside the VM. Overrides `prompt` if set.
`workdir`	string	`"/workspace"`	Working directory for the agent process.
`restart`	string	`"no"`	Restart policy: `"no"`, `"on-failure"`, or `"always"`.
`max_restarts`	int	`0`	Max restart attempts. `0` = unlimited.
`timeout`	string	—	Max run duration (`"30m"`, `"1h"`, `"2h"`). Unset = no limit.
`grace_period`	string	`"30s"`	Time between SIGTERM and SIGKILL on shutdown.
`session`	string	agent name	tmux session name.
`extra_packages`	string[]	`[]`	Additional Nix packages to install. Only valid for `type = "sandboxed"`.
`replicas`	int	`1`	Number of identical agents to launch. See Replicas.

[[shared]] section

Mount host directories into the sandbox. Each [[shared]] entry maps a host path to a guest mount point using virtio-fs. Paths are relative to the jcard.toml location.

Field	Type	Default	Description
`host`	string	—	Directory on the host machine. Required.
`guest`	string	—	Mount point inside the VM. Required.
`readonly`	bool	`false`	Prevent the agent from modifying host files.

[[shared]]
host = "./"
guest = "/workspace"
readonly = false

Multiple shared directories are supported:

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

[[shared]]
host = "/tmp/data"
guest = "/data"
readonly = true

The agent’s workdir typically points to a shared mount so that agents can read and write files on the host.

[agents.env]

Extra environment variables for the agent process.

[[agents]]
harness = "opencode"

[agents.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"

Restart policies

Policy	Behavior
`no`	Run once, never restart.
`on-failure`	Restart only on non-zero exit.
`always`	Restart on any exit, up to `max_restarts`.

Replicas

The replicas field launches multiple identical agents from a single spec. Each replica gets a unique name suffixed with its index.

[[agents]]
name = "reviewer"
harness = "claude-code"
prompt = "Review the code for bugs."
replicas = 5

This creates 5 agents: reviewer-0, reviewer-1, reviewer-2, reviewer-3, reviewer-4.

If replicas = 1 (the default), no suffix is added — the agent keeps its original name.

Replicas share the same configuration but run independently. Useful for launching swarms of agents performing the same task.

Examples

Shared workspace with an agent:

mixtape = "opencode-mixtape:latest"

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

[[agents]]
harness = "claude-code"
prompt = "Fix the failing tests."
workdir = "/workspace"

Single agent with restart and timeout:

mixtape = "opencode-mixtape:latest"

[[agents]]
harness = "opencode"
prompt = "Fix the failing tests."
workdir = "/workspace"
restart = "on-failure"
max_restarts = 3
timeout = "1h"

[agents.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"

Multiple agents in one sandbox:

mixtape = "opencode-mixtape:latest"

[[agents]]
name = "reviewer"
harness = "claude-code"
prompt = "Review the PR for security issues."

[[agents]]
name = "coder"
harness = "opencode"
prompt = "Implement the feature described in TASK.md."

Agent swarm with replicas:

mixtape = "opencode-mixtape:latest"

[[agents]]
name = "worker"
harness = "claude-code"
prompt = "Process items from the work queue."
replicas = 10

Interactive session (no prompt):

mixtape = "opencode-mixtape:latest"

[[agents]]
harness = "opencode"
workdir = "/workspace"

Sandboxed agent with extra packages:

mixtape = "opencode-mixtape:latest"

[[agents]]
harness = "claude-code"
type = "sandboxed"
extra_packages = ["ripgrep", "fd", "python311"]