---
title: Dashboard
description: Use the AO dashboard to monitor agents, respond to sessions, review PRs, manage projects, and open live terminals.
---

The AO dashboard is the control room for running agents. It shows what each session is doing, which PRs need review, where agents are blocked, and which projects are active.

Start it with:

```bash
ao start
```

By default it opens at:

```text
http://localhost:3000
```

## Read The Board

The main dashboard groups sessions by what you need to do next.

| Column      | What it means                                      | What you usually do                       |
| ----------- | -------------------------------------------------- | ----------------------------------------- |
| **Working** | Agent is actively coding or running commands       | Let it run                                |
| **Pending** | Session exists but has not started useful work yet | Check if it stays here too long           |
| **Review**  | PR is open and waiting for review                  | Review the PR or wait for CI              |
| **Respond** | Agent needs input or hit a blocker                 | Open the session and reply                |
| **Merge**   | PR is approved and checks are green                | Merge or let your merge workflow continue |

Completed and terminated sessions appear in the **Done / Terminated** area. Restore a session from there when you need to inspect or continue it.

When multiple projects are registered, the dashboard opens with a project overview. Pick a project to see its board, or use the project filter to scope dashboard, PR, and session views.

## Handle A Session

Click a session card to open its detail page.

Use the detail page to:

- Read the current status, branch, linked issue, and linked PR.
- See whether the agent is active, idle, blocked, waiting for input, or exited.
- Inspect PR size, CI checks, review state, and unresolved comments.
- Send a message to the agent.
- Kill or restore the session.
- Open the live terminal.

For review comments, use **Ask Agent to Fix** when the right next step is obvious. Use a manual message when you need to add context or constrain the fix:

```text
Keep this change limited to the API route. Do not refactor the shared client.
```

## Review PRs

Open `/prs` to see every PR created by AO-managed sessions.

The PR page lets you filter by:

| Tab        | Shows                        |
| ---------- | ---------------------------- |
| **All**    | Open, merged, and closed PRs |
| **Open**   | PRs still in progress        |
| **Merged** | Completed PRs                |
| **Closed** | Closed but unmerged PRs      |

Each PR shows its size, CI state, review decision, and unresolved threads. Use this page when you want a repository-level review queue instead of a session-by-session view.

## Manage Projects

The sidebar shows registered projects. Use it to move between projects, add another repository, or open a project's settings.

Project settings let you edit behavior fields without changing the repository identity. That means you can change things like agent, runtime, tracker, SCM, and reactions, but AO keeps the registered path, storage key, and repository identity stable.

If a project is degraded because its local config is invalid or still in an older wrapped format, the dashboard shows a repair state instead of hiding the project.

## Use The Terminal

Each session detail page includes a live terminal attached to the agent process.

Use the terminal to inspect what the agent is doing, recover from stuck prompts, or run a quick command in the session context. For normal guidance, prefer the message box; it is easier for the agent to treat as instruction.

AO has two terminal backends:

| Backend              | Used when          | Default port |
| -------------------- | ------------------ | ------------ |
| tmux WebSocket mux   | `runtime: tmux`    | `14800`      |
| direct PTY WebSocket | `runtime: process` | `14801`      |

The terminal reconnects automatically when the WebSocket drops. If terminal output works but input feels awkward on mobile, send messages from the session controls instead.

## Use AO On Mobile

On smaller screens, the dashboard switches to a mobile layout:

- A bottom tab bar links to Dashboard, PRs, and Orchestrator.
- Sessions are ordered by urgency: Respond, Merge, Review, Pending, Working.
- Tapping a card opens a bottom sheet with quick actions.
- The terminal opens in a compact full-screen style.

Mobile is useful for checking status and sending short replies. Long terminal work is still better on desktop.

## Orchestrator Sessions

When a project has an orchestrator session, the dashboard links to it from the project header or mobile tab bar.

If multiple orchestrator sessions exist for the same project, `/orchestrators?project={projectId}` lets you choose one or start a new orchestrator session.

Use the orchestrator view when you care about the whole agent fleet instead of one worker session.

## Freshness And Updates

The dashboard receives live session updates over `/api/events`. AO sends snapshots every five seconds. When sessions are added or removed, the dashboard refreshes the full session list from `/api/sessions`.

If GitHub or GitLab rate limits are hit, PR details can become stale for a short time. The dashboard shows a warning banner and refreshes automatically when data is available again.

The favicon and document title also change when sessions need attention, so you can keep the dashboard open in a background tab.

## Routes

| Route                                 | Use for                                   |
| ------------------------------------- | ----------------------------------------- |
| `/`                                   | Project overview or current project board |
| `/projects/{projectId}`               | One project's board                       |
| `/projects/{projectId}/settings`      | Project behavior settings                 |
| `/prs`                                | PR review queue                           |
| `/sessions/{id}`                      | Session detail and terminal               |
| `/projects/{projectId}/sessions/{id}` | Project-scoped session detail             |
| `/orchestrators?project={projectId}`  | Pick or start an orchestrator session     |

Internal API routes such as `/api/events`, `/api/sessions`, `/api/projects`, and `/api/spawn` are used by the dashboard. They are not a stable public API yet.

## Ports

The full dashboard experience uses three ports:

| Service                 | Default           | Config                                         |
| ----------------------- | ----------------- | ---------------------------------------------- |
| Dashboard HTTP          | `3000`            | `port` or `PORT`                               |
| tmux terminal WebSocket | auto from `14800` | `terminalPort` or `TERMINAL_PORT`              |
| direct PTY WebSocket    | auto from `14801` | `directTerminalPort` or `DIRECT_TERMINAL_PORT` |

For remote access, prefer Tailscale and keep AO off the public internet. See [Remote access](/docs/configuration/remote-access).

## Troubleshooting

**The board is empty**  
Check that the project is registered and that you are viewing the right project filter.

**A session looks stale**  
Wait one poll cycle, then refresh. If PR data is stale, check for a rate-limit banner.

**Terminal does not connect**  
Make sure the terminal WebSocket port is reachable. If you use a reverse proxy, it must forward WebSocket upgrade headers.

**A project cannot be edited**  
Fix the local config first. The dashboard only writes behavior fields when the project config loads cleanly.

**A session needs input**  
Open the session detail page and send a short, direct instruction. The agent receives it in the running session.

## Next Steps

<Cards>
	<Card title="Quickstart" href="/docs/quickstart" description="Start AO, spawn a session, and handle the first PR." />
	<Card
		title="Configuration"
		href="/docs/configuration"
		description="Understand global registry and local project settings."
	/>
	<Card
		title="Remote access"
		href="/docs/configuration/remote-access"
		description="Open the dashboard from another device safely."
	/>
</Cards>
