Dashboard · Factorial Docs

The dashboard is where operators and reviewers follow and steer the factory. It shows every ticket, the work of each agent and what it cost, and it lets you act on a ticket.

The side navigation has three screens: Overview, Projects and Runtimes. The Account menu holds Settings, with Get MCP token and Theme, and Sign out. The dashboard shows the facts of GitHub that Factorial last read. A note in the page header tells you when the data is old.

The sign-in page says Sign in to Factorial. Push Continue with Google and choose your Google account. The operator decides which Google domains may sign in. The operator sets FACTORIAL_AUTH__ALLOWED_DOMAINS in the .env file of the factory, as a comma-separated list, for example acme.example. An account whose email ends in another domain cannot sign in. The Google client ID and secret go in the same file.

The page also has Use an API token. An operator can paste the token of the deployment there. A deployment that has no Google sign-in shows only this field. A token does not name a person, so Factorial records its actions as api-token.

If your session ends, the dashboard shows Your session has expired. Sign in again to continue. To leave, open the Account menu and choose Sign out.

Overview

Overview shows the whole factory on one screen, one square for each ticket, across all projects. Each row of the board is a project. Each column is a state of a ticket:

Admitted: Factorial took the ticket in, and nothing has run yet.
Running: An agent works on the first attempt at the step.
Gate: The ticket waits for a person.
Error: The ticket stopped on a failure.
Retrying: An agent works again after a failed attempt.
Done: The ticket finished, or left the process.

The board uses these states, not the steps of a process, because each project has its own steps.

Use the page like this:

Choose All, Active or Paused to filter the projects by admission.
Push Retries, Cost, Time or Tokens to shade the squares by that figure. Hold the pointer on a button to preview it, and click to keep it. The projects with the highest values move to the top.
Click a column heading, a project or a square to focus on it. The list beside the board then shows only those tickets. Click it again to clear the focus.
In the list, search by number or title, sort the rows, and click a row to open the ticket page.
Push Reset view to clear the shading, the focus and the sort.
Push Board settings to change the values at which the shading changes colour and the size of the squares.

Projects

Projects lists each project with its repository, its runtime, whether it admits issues, and its age. Click a row to open the project. With more than ten projects, a field filters the list by name or repository.

To add a project, push Create project. Give it a name and the repository, in the form acme/app. Install the GitHub App on the repository first. A new project is not active. Connect a repository shows the steps that follow.

A project page has two tabs:

Tickets: The tickets of the project, with a status filter: All, Running, Waiting at gate, Stopped, Done, Exited and Admission. You can sort by runs, cost and the time of the last update. Admission lists the open issues that are not tickets yet and what each one waits for. The header shows what the project has spent.
Configuration: What the project needs before it can run: the GitHub App, the config branch, secrets, labels, branch protection, the runtime and the process config. A badge on the tab counts what still blocks activation.

The button in the header controls admission. A project that is ready shows Activate project. Factorial then admits matching issues and starts agents, which spend tokens. An active project shows Pause admission. A project that is not ready shows View pending configuration step, which takes you to the first blocker.

A ticket's page

Click a ticket anywhere to open its page. The header shows the issue number and title, the status, the step, the owner and the time of admission. It also shows the actions for the ticket.

The process graph shows the process that the ticket pinned at admission. It marks the current step and the steps that ran, and it shows how many attempts a step used. Click a step to go to its attempt in the activity.
The Activity panel lists every attempt of every step, newest first or oldest first. Each attempt shows its status, its tokens and its estimated cost. The totals for the ticket are in the panel header.
The Output button of an attempt opens a drawer with the Transcript of the agent. When the step has a preview, the drawer also has a Preview section. A run with a terminal has a Terminal section.

A message under the header says what the ticket asks of you, for example Waiting for a review, Waiting on you or Quarantined.

The actions

Refresh: Reads the ticket from GitHub now.
Interrupt: Stops a running agent step and keeps its session. It is in the header of the attempt.
Retry now: Starts a booked retry before its delay ends.
Exit and Re-enter: Takes the ticket out of the process, or brings it back.
Unblock: Releases a blocked or rejected ticket, like removing factorial:blocked.
Requeue: Tells Factorial to retry a quarantined ticket.
Request changes: Sends the work of a gate back to the agent. The dashboard cannot approve.

Each action asks for a confirmation. Tickets and gates explains what each one does to the ticket.

The terminal

The Terminal section of the output drawer connects you to the session of an agent that runs in interactive mode. A parked session shows Resume session. A run that Factorial kept shows Open session, which opens the session read-only.

An operator must turn the terminal on for the deployment. The Terminal section shows how.
Anyone who can sign in to the dashboard can use the terminal.
Every viewer attaches read-only. A run has one writer seat. Push Type here to take it. When someone else has it, Take over asks first. The seat frees after two minutes without typing.
Factorial records who typed and how many bytes. It never records the text, and it stores nothing from the screen.

On a host runtime, write access is a shell as the user of the worker. Give the dashboard only to people you trust with that user. The terminal has the rules.

Edit a process

The process builder is on the Configuration tab of a project, in the Process config section. It shows each lane of the project as a graph. Use it to read a config, change it and put the change into use.

Choose the lane. Push Show config to read its file, or New lane to start from a template. A project without a config shows Write a config.
Edit the config in the drawer. A label shows Valid config or Invalid config, and the errors appear under the text.
Review the files that the commit would write. They include the folder of each agent that the config names and that the branch does not have yet. You can include or leave out each file, and edit its text.
Push Commit and sync.

Commit and sync is the approval of a config change. Factorial writes the commit on the factorial branch as the GitHub App and then syncs that commit. Factorial writes nothing before you push it. A file that the branch already has is never replaced, unless you edit it. If the branch moved since you opened the editor, Factorial refuses the commit and changes nothing.

If the config names a runtime that the project does not allow yet, Permit and commit adds it to the list and commits. Set as default makes a lane the one that issues without a process label use. Sync from repo reads the branch again. Processes explains the file. Connect a repository explains the sync.

Change requests

A change request sends the work of a gate back to the agent without a GitHub review. The form opens from Request changes in the Waiting for a review message of the ticket page. It also opens from the Preview section of the output drawer, so you can send back a page that you reviewed there. The activity then shows Change request sent.

A change request can only reject. It cannot approve, merge or move the ticket on. Decide a gate has the steps and says what happens next. Previews explains how a preview shows work in the dashboard.

Runtimes

Runtimes lists the places where agents run. Each row has the name, the slug, the type, the number of repositories that use it, and whether it has a credential. Push Create runtime to add one. Click a row to open its page, which shows its details, credentials, metadata and connected repositories, and lets you delete it. Register a runtime explains the fields.

MCP access

An MCP client, for example Claude Code or Codex, can use Factorial through its MCP server. MCP access gives the client a token. To open it, choose Settings and then Get MCP token in the Account menu.

Push New token.
Give the token a label, for example the name of the machine.
Choose the access: Read lists projects and tickets and reads metrics and config. Write also creates tickets, acts on them and commits config.
Copy the token. The page shows it once. Push Done when you saved it.

The page also shows the address of the server and the tokens that you made. Under Connect a client, it has setup commands for Claude Code and Codex. It also lists the tools. A token lasts one year. If you signed in with Google, that sign-in must be from the last 24 hours. MCP client explains how to use it.