> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Share agent environments with gandalf.toml

> Declare team-wide MCP servers, skills, and hooks in gandalf.toml. Detect drift with gandalf check and apply safely with a pre-apply snapshot.

Gandalf's team manifest lets you declare a shared AI agent environment as code. Commit a `gandalf.toml` at the repository root, and teammates get a repeatable Codex and Claude Code setup with drift detection and non-destructive apply.

<Steps>
  <Step title="Initialize the manifest">
    Create the manifest and skills directory. Use `--from-current` to scaffold from your local setup.

    ```bash theme={null}
    gandalf init --name my-team-project
    gandalf init --from-current
    ```

    This writes `gandalf.toml` and `.gandalf/skills/`. Use `-f` to overwrite an existing manifest.
  </Step>

  <Step title="Edit gandalf.toml">
    Declare MCP servers, skills, hooks, and an env template. `${ENV_VAR}` interpolation is supported.

    ```toml gandalf.toml theme={null}
    version = "1.0"
    name = "my-team-project"
    description = "Standardized AI agent environment"
    agents = ["claude-code", "codex"]

    [mcp_servers.postgres-db]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    required_env = ["DATABASE_URL"]
    description = "Shared staging database MCP server"

    [hooks.pre-save-lint]
    event = "before_save"
    command = "./scripts/lint.sh"

    [env_template]
    DATABASE_URL = "postgres://user:password@localhost:5432/db"
    ```

    See the [manifest reference](/reference/manifest) for the full field list.
  </Step>

  <Step title="Commit the manifest to git">
    Commit `gandalf.toml` and `.gandalf/skills/` so teammates get the same setup on checkout.
  </Step>

  <Step title="Check for drift">
    Compare the manifest to each local agent. Add `--ci` to exit non-zero on drift for use in CI.

    ```bash theme={null}
    gandalf check
    gandalf check --ci
    ```

    Output lists missing MCP servers, skills, or hooks per agent, with target file paths.
  </Step>

  <Step title="Apply the manifest">
    Preview, then apply. Apply runs Smart Merge (non-destructive) and creates a pre-apply safety snapshot.

    ```bash theme={null}
    gandalf apply --dry-run
    gandalf apply --yes
    ```

    On success, Gandalf prints the safety snapshot name so you can roll back:

    ```bash theme={null}
    gandalf restore --snapshot <backup> --apply --experimental
    ```
  </Step>
</Steps>

<Note>
  Smart Merge only adds or updates entries declared in the manifest. It does not delete or modify unrelated personal user settings.
</Note>

## Related

* [`gandalf init` reference](/cli/init)
* [`gandalf check` reference](/cli/check)
* [`gandalf apply` reference](/cli/apply)
* [Manifest reference](/reference/manifest)