Skip to main content
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

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

Overview

Every board in the project rendered as a wall you can scan at once — useful for a quick status check across multiple workflows.

Board

A live kanban with one column per workflow group. Switch to List view with a single click.

Task

Full description, custom fields, comments, and event history for a single task. A task blocked on a human gate carries a “pending approval” pill.

Markdown rendering

Author-supplied markdown in descriptions and comments is rendered through a single sanitized path.

​
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

The UI observes. It never writes: no drag-and-drop, no inline editing, no buttons that change state.
This is intentional for two reasons:
1

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

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.

​
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.
Different projects can serve simultaneously — each binds to its own port from the 7475–7499 range. Run one serve per project directory without conflict.