The dashboard

The dashboard is one page in your browser, served by the run itself. It shows what every slot and agent is doing, takes the same controls as the command line, lists everything the run waits on you for, and holds the settings and the set-up checklist. This page walks through each tab; the questions and actions on Waiting on you have their own page.

Opening it, and reaching it from another machine

foreman run starts the dashboard itself while console.adapter is dashboard (the default) and prints its address. To watch without a run, foreman dashboard [--port N] [--host H] serves the same page in the foreground until Ctrl-C. Host and port default to console.host and console.port in foreman.config.json: the loopback address of this computer, port 4317. A port already in use is reported with a hint to try --port; a project with no foreman.config.json is pointed at foreman setup. The run also honours FOREMAN_DASHBOARD_HOST as the address to listen on; the container runner sets it so the page can be reached from outside the container.

On the loopback address the page needs no token, but the server only answers requests addressed to this computer (a Host check against DNS rebinding). On any other host it needs FOREMAN_DASHBOARD_TOKEN, read from the environment, from .env.foreman or from the project’s env file, and refuses to start without one. Every request then carries the token as Authorization: Bearer <token>; since the browser opens the page itself, put ?token=<value> at the end of the address, and the page keeps it in memory for its own requests. The Set up tab can generate the token for you. A request from another page’s origin is refused, a POST must be JSON, and bodies are capped at 64 KB.

Some things work only on a dashboard on this computer, token or not: saving and testing keys, the agents’ conversations, the project check run, the Jira and Salesforce sign-ins and the cloud secrets. An SSH tunnel to the loopback address counts as this computer, which is the simplest way to use everything from another machine.

The page updates live over server-sent events, with a comment every 15 seconds to keep the connection open. When that link drops it polls /api/status every 10 seconds instead, and tries the live link again after 30 seconds. The header’s Link pill reads Connecting, Live, Polling or Lost. The header also shows the run’s Status, Slots busy, Updated (how long since the run last wrote), Local time and the Theme picker. Above the tabs an alert appears when the page needs its token, when the run has gone quiet (the computer may be asleep, or the run may have stopped), when the run is halted or stopped with the reason, and when it is running but stuck.

Command centre

The first tab is the run at a glance. Every button on it carries a one-line hint underneath and a fuller tooltip on hover and focus, the same words as the Waiting on you tables. After you press one, the page says “Sent. The run acts on it at its next check.”

Waiting on you is the panel at the top: the one-line headline that says why the factory is idle or what it builds (the same line as the Waiting on you tab), a count such as “6 need you · 9 later”, and Open Waiting on you.

Now building has one lane per slot, side by side on a wide screen and stacked on a phone, with “N of M busy” in its heading. A lane shows the slot’s id, its state (Building, Waiting to ship, Held, Idle, Parked, Down), the model it runs on, the story’s id and group, its title, the stage pipeline (Design, Build, Test, Review, Commit, Release) with the current stage named, how long the slot has been on it, the build round (“build round 2 of 3”), the story’s latest detail and a link to its pull request. Open the lane for more: why a slot is parked, down or held, in the run’s own words with what each button would do; an agent card for every agent running, which says in plain words what the agent is doing, its stage, its run time, how many steps it has taken, how long it has been quiet, the model it is on (a review running through an outside engine shows the reviewer, such as Security, “via Antigravity”, on the engine’s model), Show command for the raw command and View conversation, which opens the agent’s conversation in a dialog (the Foreman card opens the story session’s own) and refreshes it every 3 seconds while the agent runs; the agents already finished with their durations; and the slot’s buttons: Skip story, Take over, Park or Park after this story, Unpark, Resume, Restart fresh from main, Resume as is, and Discard changes and reset, which asks first. Slot actions says what each does.

Run details is a card with five sub-tabs:

• Live feed: the 40 newest events, each with its time, its slot and its text: every agent start and finish, stage and result.
• Up next: work queued for a slot (a story waiting for a slot under the worker count), the run order (up to 8 stories, each with its title or “Waits on a story ahead of it”), a line for how many more wait on you or on stories ahead of them, and Taken by you: the stories you took over, each with Hand back. The run leaves those alone until you hand them back.
• Finished: Ready to promote, the stories whose release waits on someone such as a promotion click, each with its reason, when it parked, when it was last checked and its pull request; then the shipped, blocked and failed stories with a result chip, the time, duration, cost, rounds, a note and the pull request. The heading carries this run’s totals: stories, shipped, cost and time.
• Progress: the share of stories done, with done, to do and blocked counts, and a grid per group when the stories have groups.
• Tokens: tokens per agent role for today, the last 7 days, this run and the last 14 days as a sparkline, with the models each role ran on; per story over the last 14 days; and hints on where to save. It shows tokens only, never money. Costs and reports has the same view as foreman report --tokens.

Controls are the owner’s commands from Run, pause and stop: Pause, which reads Resume while the run is paused, by you or by itself, with a note that says which; I’ve fixed it, shown only while the run is halted, with what still fails after a check that did not pass; Workers, one button per slot count, saved as the workers setting for this computer and applied at the next pick; Build this story next, a list of the stories that can be built right now and Request; and Stop the run, which asks first and then finishes the stories in progress. The stop note names who asked for a stop that is under way.

Readout shows how many agents are online and a short table: Shipped lately, Blocked, Failed review, Buildable now, Waiting on you (so many to answer, or Nothing now), and For later (owner tasks and parked decisions), with the titles of what waits and a link to the tab.

Insights

Insights is drawn from the run records in .foreman/runs/, one per story session, which the features.costMetrics switch keeps. Days are UTC, by when a story ended, so they line up with the Tokens view. Nothing shows until a story has finished.

Four tiles cover the last 7 days: Stories shipped, with the daily average; Ship rate, the share of finished stories that shipped and how many did not; Typical time to ship, the median minutes of the shipped stories and the share that shipped on the first try (one round); and Spend, with the spend per shipped story.

Four charts follow, each with its numbers as a table: Velocity, stories shipped and not shipped per day over the last 14 days; Usage by agent, tokens each day by role, cache reads included; Spend per day, what the stories that finished each day cost; and Where the time goes, the average minutes a shipped story spent in Design, Build, Test and Review over the last 7 days. The same records feed foreman report.

Waiting on you

The third tab lists everything the run needs from you, most urgent first, as cards in five sections: Needs you now, Your tasks, Quick decisions, Later and FYI. The tab’s badge counts only what you can act on now. Above the cards the headline says why the factory is idle or what it builds, and Go to it scrolls to the one card to deal with first. Under the cards sit the Answered list, where an answer the run has not yet used can still be changed, and the Learned list, one row per change Foreman learned by itself with Undo on each still in force. Waiting on you covers every card and button.

Settings

The Settings tab lists every setting that applies to this project in groups: Run, Agent models, Features, Learning, Release, Jira, Notify and Dashboard. Each row has a control, where its value comes from (Foreman’s default, the team’s foreman.config.json, or this computer) and an info button whose popup says what the setting does, its default, what is allowed, who set it, when it takes effect and its config key. Two buttons save: Save for me changes this computer only, and Save for the team writes foreman.config.json, which everyone gets once it is committed. A value saved for you wins over the team’s. A row with a value of its own also offers Reset my value or Reset the team value. A banner at the top reminds you to commit foreman.config.json while git shows it changed, and a warning appears by any local value Foreman ignores, with the reason. Settings explains the layers and when a change takes effect.

Agent models has a dropdown per role, one for the story session itself (session.model), and for each reviewer an engine row written as engine:model, such as antigravity:claude-opus-4-6-thinking. Emptying the engine row turns the engine off for that reviewer; its model row is then the model it runs on, not the one it falls back to. Agents and traits has the details.

Set up

The Set up tab walks through making Foreman ready on this project: a wizard of one step per screen the first time, then a checklist by area with a status pill, a line of state and Open on each step. While a required step is missing the tab comes first, with its done-of-total count. It is where keys are saved, tested and generated, where Jira, notifications, the Salesforce orgs and the cloud runner are set up, and where a project with no foreman.config.json writes one. The Set up tab goes through every step.

The Help tab opens this documentation.

Theme

The Theme picker in the header offers System, Light and Dark. System, the default, follows the computer: light, or dark when the computer is set to dark. Light or Dark is this browser’s own choice, remembered in the browser and nowhere else. Everything on the page is inline; it loads nothing from elsewhere.