gandalf.toml team manifest reference

gandalf.toml is the team manifest that Gandalf reads when you run gandalf init, gandalf check, and gandalf apply. It declares the MCP servers, skills, hooks, and environment templates your team wants present in local agent setups. This page describes every supported field and shows a complete annotated example.

File structure overview

A manifest is a TOML file with a top-level metadata section, plus optional sections for MCP servers, skills, hooks, and environment templates. Not all sections are required: include only the ones your team manages centrally.

Top-level fields

# Required: manifest schema version
version = "1.0"

# Required: project or team name
name = "my-team"

# Optional: short description of this manifest
description = "Shared setup for backend squad"

# Required: list of agents this manifest targets
agents = ["claude-code", "codex"]

Field	Type	Required	Description
`version`	string	Yes	Manifest schema version. Must be `"1.0"`.
`name`	string	Yes	Name of the team or project. Used in snapshot and report names.
`description`	string	No	Human-readable summary of the manifest purpose.
`agents`	array of strings	Yes	Agent IDs to target. Valid values: `codex`, `claude-code`.

MCP servers

Declare MCP (Model Context Protocol) servers under [mcp_servers.<name>]. Each server must define either a command with optional args, or a url for HTTP-based servers.

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Filesystem access for project context"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Stripe customer data"

Field	Type	Required	Description
`command`	string	Yes (unless `url`)	Executable to run the MCP server.
`args`	array of strings	No	Arguments passed to `command`. Supports `${ENV_VAR}` templates.
`url`	string	Yes (unless `command`)	HTTP endpoint for the MCP server. If set, do not include `command` or `args`.
`headers`	table of strings	No	Headers sent with each request. Supports `${ENV_VAR}` templates.
`required_env`	array of strings	No	Environment variables Gandalf checks before applying the server.
`description`	string	No	Human-readable summary of what the server provides.

Any field that accepts ${ENV_VAR} will be expanded at apply time, not when the manifest is parsed. This lets you commit shared manifests without embedding secrets.

Skills

Declare skills in a [[skills]] array-of-tables. Each entry names a skill and its source.

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "SQL skill for PostgreSQL introspection"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment helper"

Field	Type	Required	Description
`name`	string	Yes	Skill identifier. Must match the name the agent expects.
`source`	string	Yes	Where the skill comes from. Can be a marketplace URI, a Git URL, or a local path.
`description`	string	No	Human-readable summary of the skill.

Hooks

Declare agent hooks under [hooks.<name>]. Each hook binds an event to a command.

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

Field	Type	Required	Description
`event`	string	Yes	Event name that triggers the hook.
`command`	string	Yes	Command to run when the hook fires.

Environment templates

Use [env_template] to document expected environment variables. Gandalf does not write these into shell profiles; it uses them for drift checks and reports.

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"

Each key is the environment variable name, and each value is an example default. Gandalf compares these against the current environment during check and highlights missing variables.

Full annotated example

# gandalf.toml
# Full team manifest for backend squad

version = "1.0"
name = "backend-squad"
description = "Shared Codex and Claude Code setup for backend engineers"
agents = ["claude-code", "codex"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Read project files via MCP"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Live Stripe customer lookup"

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "PostgreSQL introspection helper"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment scripts"

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
STRIPE_API_KEY = "sk_test_..."

Check and apply behavior

gandalf check compares your manifest against the current local agent setup and reports drift. When run with --ci, it exits with code 1 if any drift is found. This makes it suitable for CI pipelines that enforce team standards.

gandalf apply runs Smart Merge (non-destructive) and creates a pre-apply safety snapshot before changing anything. If the manifest targets an unsupported agent directory, apply skips that agent and logs a warning.

For command-line flags and workflow details, see /cli/init, /cli/check, and /cli/apply. gandalf.toml is the team manifest that Gandalf reads when you run gandalf init, gandalf check, and gandalf apply. It declares the MCP servers, skills, hooks, and environment templates your team wants present in local agent setups. This page describes every supported field and shows a complete annotated example.

File structure overview

Top-level fields

# Required: manifest schema version
version = "1.0"

# Required: project or team name
name = "my-team"

# Optional: short description of this manifest
description = "Shared setup for backend squad"

# Required: list of agents this manifest targets
agents = ["claude-code", "codex"]

Field	Type	Required	Description
`version`	string	Yes	Manifest schema version. Must be `"1.0"`.
`name`	string	Yes	Name of the team or project. Used in snapshot and report names.
`description`	string	No	Human-readable summary of the manifest purpose.
`agents`	array of strings	Yes	Agent IDs to target. Valid values: `codex`, `claude-code`.

MCP servers

Declare MCP (Model Context Protocol) servers under [mcp_servers.<name>]. Each server must define either a command with optional args, or a url for HTTP-based servers.

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Filesystem access for project context"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Stripe customer data"

Field	Type	Required	Description
`command`	string	Yes (unless `url`)	Executable to run the MCP server.
`args`	array of strings	No	Arguments passed to `command`. Supports `${ENV_VAR}` templates.
`url`	string	Yes (unless `command`)	HTTP endpoint for the MCP server. If set, do not include `command` or `args`.
`headers`	table of strings	No	Headers sent with each request. Supports `${ENV_VAR}` templates.
`required_env`	array of strings	No	Environment variables Gandalf checks before applying the server.
`description`	string	No	Human-readable summary of what the server provides.

Any field that accepts ${ENV_VAR} will be expanded at apply time, not when the manifest is parsed. This lets you commit shared manifests without embedding secrets.

Skills

Declare skills in a [[skills]] array-of-tables. Each entry names a skill and its source.

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "SQL skill for PostgreSQL introspection"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment helper"

Field	Type	Required	Description
`name`	string	Yes	Skill identifier. Must match the name the agent expects.
`source`	string	Yes	Where the skill comes from. Can be a marketplace URI, a Git URL, or a local path.
`description`	string	No	Human-readable summary of the skill.

Hooks

Declare agent hooks under [hooks.<name>]. Each hook binds an event to a command.

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

Field	Type	Required	Description
`event`	string	Yes	Event name that triggers the hook.
`command`	string	Yes	Command to run when the hook fires.

Environment templates

Use [env_template] to document expected environment variables. Gandalf does not write these into shell profiles; it uses them for drift checks and reports.

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"

Each key is the environment variable name, and each value is an example default. Gandalf compares these against the current environment during check and highlights missing variables.

Full annotated example

# gandalf.toml
# Full team manifest for backend squad

version = "1.0"
name = "backend-squad"
description = "Shared Codex and Claude Code setup for backend engineers"
agents = ["claude-code", "codex"]

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/workspace"]
description = "Read project files via MCP"

[mcp_servers.stripe]
url = "https://api.stripe.com/v1/mcp"
headers = { Authorization = "Bearer ${STRIPE_API_KEY}" }
required_env = ["STRIPE_API_KEY"]
description = "Live Stripe customer lookup"

[[skills]]
name = "postgres-query"
source = "marketplace://postgres-query"
description = "PostgreSQL introspection helper"

[[skills]]
name = "custom-deploy"
source = "git+https://github.com/acme/corp-deploy-scripts"
description = "Internal deployment scripts"

[hooks.pre-commit]
event = "pre-commit"
command = "gandalf-check"

[env_template]
DATABASE_URL = "postgres://user:pass@localhost:5432/dev"
REDIS_URL = "redis://localhost:6379"
STRIPE_API_KEY = "sk_test_..."

Check and apply behavior

For command-line flags and workflow details, see /cli/init, /cli/check, and /cli/apply.

Get Started

Concepts

Guides

Reference

gandalf.toml team manifest reference

File structure overview

Top-level fields

MCP servers

Skills

Hooks

Environment templates

Full annotated example

Check and apply behavior

File structure overview

Top-level fields

MCP servers

Skills

Hooks

Environment templates

Full annotated example

Check and apply behavior

​File structure overview

​Top-level fields

​MCP servers

​Skills

​Hooks

​Environment templates

​Full annotated example

​Check and apply behavior

​File structure overview

​Top-level fields

​MCP servers

​Skills

​Hooks

​Environment templates

​Full annotated example

​Check and apply behavior

File structure overview

Top-level fields

MCP servers

Skills

Hooks

Environment templates

Full annotated example

Check and apply behavior

File structure overview

Top-level fields

MCP servers

Skills

Hooks

Environment templates

Full annotated example

Check and apply behavior