> ## 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.

# The Substrate Web UI: Read-Only Live Kanban Inspector

> Run substrate serve for a localhost kanban that auto-refreshes as agents work. Covers read-only design, port scanning from 7475, and single-owner lock.

The Substrate web UI is a localhost-only, read-only inspector that lets you watch work happen in real time. Start it alongside your editor or agent runtime and see tasks land in columns without touching the database yourself.

## Starting the server

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

Running bare `substrate` with no subcommand is an alias for `serve`. The server binds to `127.0.0.1` on port `7475` by default. If that port is taken, Substrate scans upward through `7475–7499` and binds to the first free port, printing the URL it actually used. The bound port is recorded in `.substrate/serve.json`.

## What you see

<CardGroup cols={2}>
  <Card title="Overview" icon="layout-dashboard">
    Every board in the project rendered as a wall you can scan at once — useful for a quick status check across multiple workflows.
  </Card>

  <Card title="Board" icon="columns">
    A live kanban with one column per workflow group. Switch to List view with a single click.
  </Card>

  <Card title="Task" icon="file-text">
    Full description, custom fields, comments, and event history for a single task. A task blocked on a human gate carries a "pending approval" pill.
  </Card>

  <Card title="Markdown rendering" icon="align-left">
    Author-supplied markdown in descriptions and comments is rendered through a single sanitized path.
  </Card>
</CardGroup>

## Auto-refresh

The board view polls continuously. When an agent moves a task, the UI reflects it within seconds. Leave the browser open beside your editor and watch work land without refreshing manually.

## Read-only by design

<Note>
  The UI **observes**. It never writes: no drag-and-drop, no inline editing, no buttons that change state.
</Note>

This is intentional for two reasons:

<Steps>
  <Step title="Truthful event log">
    Every write in Substrate is attributed to an actor — an agent name or a `human:<os-user>` stamp. A UI that could write anonymously would corrupt that record.
  </Step>

  <Step title="Deliberate human write channel">
    The one write path reserved for people — `substrate approve` — is a CLI command precisely so it cannot be clicked by accident. Keeping the UI read-only preserves that asymmetry.
  </Step>
</Steps>

## One owner per directory

`substrate serve` takes a single-owner lock via `.substrate/substrate.pid`. A second `serve` in the same project refuses to start while the first is alive. A stale PID file left by a crashed process is reclaimed automatically.

<Tip>
  Different projects can serve simultaneously — each binds to its own port from the `7475–7499` range. Run one `serve` per project directory without conflict.
</Tip>