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

# Quickstart: Initialize a Board and Connect an Agent

> Initialize a .substrate/ directory, browse your board in the local inspector, connect an agent, and watch it move tasks through your workflow in minutes.

Run all of the following commands from the root of the project you want to track. Substrate creates its files in a `.substrate/` directory at that location — this is the working directory your agent runtime must also use when it spawns the MCP server.

<Steps>
  <Step title="Initialize a .substrate/ directory">
    Create a blank Substrate workspace in your project:

    ```sh theme={null}
    substrate init
    ```

    Or start with the bundled `web-delivery` starter — a ready-made board with a **Spec → Plan → Build → Review → QA → Done** pipeline and pre-configured gates:

    ```sh theme={null}
    substrate init --template web-delivery
    ```

    You can also pass a path to a local directory that contains a published workflow definition in place of a template name.
  </Step>

  <Step title="Open the local inspector">
    Start the read-only web inspector to browse your board:

    ```sh theme={null}
    substrate serve
    ```

    This opens the inspector at **[http://localhost:7475](http://localhost:7475)**. If that port is already in use, Substrate scans ports 7475–7499 and prints the URL it actually bound. The board view auto-refreshes within seconds as task state changes.
  </Step>

  <Step title="Connect your agent">
    Register the stdio MCP server with your agent runtime, then ask the agent to call `whoami` to confirm the connection. Full instructions are in the [MCP setup guide](/getting-started/mcp-setup).
  </Step>

  <Step title="Let the agent work">
    Once connected, your agent follows this loop:

    ```text theme={null}
    whoami → get_board_substrate → list_tasks → create_task / update_task
    ```

    Every write operation returns an envelope that names the policies that fired. Your agent uses that feedback to stay within the workflow's rails without any additional prompting.
  </Step>
</Steps>

## What gets created

After `substrate init`, your project gains the following structure:

```text .substrate/ theme={null}
.substrate/
├── config.json          # project id, name, schema version   (committed)
├── boards/<id>.json     # your workflow, as code             (committed)
├── members/<id>.json    # optional roster of personas        (committed)
├── data.sqlite          # tasks, comments, event log         (gitignored)
├── logs/substrate.log   # warnings and errors                (gitignored)
├── substrate.pid        # single-owner lock while serving    (gitignored)
└── serve.json           # the port serve actually bound      (gitignored)
```

<Tip>
  Commit `config.json` and your `boards/` and `members/` files. They are your workflow definition — versioned, diffable, and reviewable like any other code.
</Tip>

<Warning>
  Workflow definitions travel with git; task state does not. This is deliberate. A fresh clone or a new git worktree starts with an empty database. Read the [worktrees and clones guide](/agents/worktrees-and-clones) before you create a worktree — there are sharp consequences if the MCP server resolves to the wrong `.substrate/`.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="MCP Setup" icon="plug" href="/getting-started/mcp-setup">
    Register the stdio MCP server and install the agent skill for Claude Code.
  </Card>

  <Card title="How It Works" icon="circle-info" href="/concepts/how-it-works">
    Understand boards, stages, gates, and the policy envelope in depth.
  </Card>
</CardGroup>