Dashboard
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:
ao startBy default it opens at:
http://localhost:3000Read 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:
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.
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.