The rig.toml manifest

rig.toml lives at the root of a rig workspace. It declares everything the workspace needs to function — identity, what gets shared, runtime requirements, permissions, lifecycle hooks, optional collaboration settings.

The CLI reads it on every command. rig doctor checks observed state against it. rig pack uses it to build the artifact. rig install uses it to set things up.

Anatomy

[rig]
name        = "market-researcher"
author      = "maria"
version     = "1.2.0"
description = "Equity research workspace with yfinance + macro MCPs."
runtime     = "claude-code"

[package]
include = ["data/templates/**", "examples/**"]
exclude = ["data/portfolios/**"]

[env]
required = ["FINANCIAL_DATASETS_API_KEY"]
optional = ["OPENAI_API_KEY"]
template = "scripts/.env.example"
target   = ".env"

[tools]
required = ["claude", "uvx"]

[mcp]
config  = ".mcp.json"
servers = ["yfinance", "macro"]

[plugins]
required = ["claude-code-mcp-fileshare"]

[permissions]
allow = ["Bash(uvx *)", "Read(data/templates/**)"]
deny  = ["Bash(rm -rf *)"]

[local]
dirs = ["data/portfolios", "outputs"]

[install]
commands = ["uv sync"]

[run]
entrypoint   = "claude"
instructions = "cd {install_dir} && claude"

[sync]
provider = "tap"
relay    = "https://tap-relay.fly.dev"
enabled  = true

Pages

Each section gets its own page with every field, every default, and every side effect.

• [rig] — identity (name, author, version, runtime).
• [package] — include/exclude for the artifact.
• [env] — environment variables.
• [tools] — CLI tools that must be on PATH.
• [mcp] — MCP servers.
• [plugins] — Claude Code plugins.
• [permissions] — Claude allow/deny rules.
• [local] — folders that are shape-only (not shipped).
• [install] — shell hooks for setup.
• [run] — entrypoint and run instructions.
• [sync] — opt into shared-rig collaboration.

Validation

[rig] is the only required section. All five of its fields (name, author, version, description, runtime) must be present and must be strings. Other sections are optional; missing fields fall back to documented defaults.

runtime currently only accepts "claude-code". Other runtimes are intentionally out of scope until they arrive.

See also

• Concepts — manifest, artifact, workspace, source.
• Doctor JSON contract — how the manifest's declarations turn into runtime checks.