> ## Documentation Index
> Fetch the complete documentation index at: https://docs.builddown.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Admin UI reference for AI-Implement
> What the AI-Implement admin dashboard lets you manage — every panel under Work, Configure, Platform, and Developer, plus the full JSON API reference.
The admin UI at `/admin` is the control panel for your AI-Implement orchestrator. It is protected by the `ADMIN_ACCESS_CODE` environment variable — if that variable is not set, the UI is disabled and all `/admin` and `/api/*` routes return `404`. Every panel below is also reachable programmatically through the JSON API at the bottom of this page.
The sidebar organizes panels into four groups:
* **Work** — Overview, Issues, Pipelines, Pull requests, Blockers
* **Configure** — Projects, Pipelines & steps, Models & providers
* **Platform** — Runners, Sessions, Reaper, Secrets, Settings
* **Developer** — Audit log, Customizations
The headings below follow the same order.
## Work
### Overview
The main dashboard. Shows real-time orchestrator health:
* Running jobs (with duration)
* Failed jobs in the last 24 hours
* Capacity utilization across all projects
* Projects at concurrency cap
* Stale workflow templates in target repos
* A 24-hour dispatch trend chart
Environment-status checks (ticketing connection, runner callback, gap-fill trigger) appear here too — this is the first place to look if a run hasn't dispatched as expected.
### Issues
The AI-Implement inbox. Shows every issue matched by the configured project mappings, its current state (started / completed / cancelled), and whether each is ready for implementation or still has planning pending.
A second table breaks down in-progress counts by project mapping for real-time visibility into which scopes are currently working.
### Pipelines (jobs)
The dispatch log under its real internal name (`jobs` in the sidebar).
Shows the last \~500 dispatch entries (timestamped) across all teams with full execution history:
* Issue ID
* Repo
* Team (the `teamKey` shown in the row)
* Runner mode (GitHub Actions or Fly Machines)
* Session image
* Combined planning-and-implementation statuses
* Pull-request links
* Dispatch number (for re-dispatches)
Planning and implementation dispatches for the same issue are grouped visually as a single job.
Use this log to audit activity or diagnose why an issue was or was not picked up.
### Pull requests
Lists every bot-opened pull request the orchestrator is tracking, with the following information:
* Issue link
* Repo
* Current job status (`running` / `completed` / `failed` / `review_failed`)
* Iteration count (the dispatch number)
* Time since last dispatch
* Direct links to GitHub
Useful for spotting PRs that are stalled or failing review without scanning each repo individually.
### Blockers
Surfaces issues that are currently *not* being picked up despite being eligible.
KPI cards show:
* Total blocked issues
* Teams affected (distinct teams with at least one blocked issue)
* Count blocked by concurrency cap
* Count blocked by dedup window
Per-issue rows include:
* Issue identifier
* Project mapping
* Blocking reason
* Direct link back to the ticket
## Configure
### Projects (team/repo mappings)
The Projects panel is where you connect ticketing scopes (Linear teams or Jira JQL clauses) to GitHub repositories and control exactly how AI-Implement dispatches runs for each scope.
See [Configure project mappings](/configuration/team-repo-mappings) for the full field reference and defaults.
#### Create a new project mapping
Click **Configure → Projects → + New project**. The stepper walks through 8 configuration steps.
Pick **Linear** or **Jira** as the ticketing system, fill in the provider-specific config (Linear team key, or Jira JQL + repo-field value), then enter **GitHub Owner** and **Repository Name** — these are the **target repository**, not the orchestrator repo.
Runner, Provider, Capacity, Secrets, and Review steps follow. For a first run, defaults are reasonable.
Setting `provider` to `bedrock` requires `awsRegion` and is not compatible with `executionMode: fly-machines`.
You must also add `AWS_BEDROCK_ROLE_ARN` as a secret in the target repo and set the `AI_IMPLEMENT_PROVIDER` and `AI_IMPLEMENT_AWS_REGION` repo variables so comment-triggered gap-fill runs use the same auth path.
Click **Create project**. The new mapping appears in the Projects table automatically — if it does not, reload the page.
Each row in the Projects table also exposes a **Sync workflows** action, which opens or updates a pull request in the target repo containing the workflow files and starter prompts. This is the normal way to push workflow updates from the orchestrator into target repos.
### Pipelines & steps
Shows the pipeline YAML definitions (the built-in `src/pipeline/*.yml` plus any `custom/pipelines/*.yml` overrides) as collapsible details, each listing the steps that run and their module IDs.
A second table lists every step module with:
* Built-in path
* Custom override path (if present)
* Status (`built-in` / `override` / `additive`)
Useful for visualizing the extension hierarchy when you've added custom steps. See [Add custom pipeline steps](/customize/custom-steps) for the override mechanism.
### Models & providers
Read-only summary of model provider and region per project mapping.
Model IDs themselves live in each target repo's `WORKFLOW.md` and `PLANNING.md` front matter — this page doesn't edit them.
KPI cards show:
* **Projects** (total)
* **Anthropic** (count of projects using the Anthropic provider)
* **Bedrock** (count of projects using the Bedrock provider)
* **Bedrock regions** (count of distinct regions in use)
The table lists each project's:
* Team (the `teamKey`)
* Repo
* Provider badge (`anthropic` or `bedrock`)
* Bedrock region (or a "missing" badge if required and unset)
* Planning status
* Runner mode
## Platform
### Runners
High-level runner-infrastructure dashboard.
KPI cards show:
* Current runner-mode override (`default` / `gha` / `fly` / `shadow`)
* Live Fly session count
* Capacity utilization (in-progress runs vs. total cap across mappings)
* 24-hour reaper destructions
A live-sessions table (top 8) links into the **Sessions** panel for the full list.
A per-project table shows each mapping's:
* Configured execution mode
* Effective mode (after applying any global override)
* Capacity-utilization meter
### Sessions
Lists every Fly Machine session currently in `started`, `starting`, or `created` state.
Each row shows:
* Machine ID and name
* Current state
* Uptime duration
* Associated issue identifier (linked to the ticketing system), where available
* Target repo, where available
You can destroy a stuck session directly from this panel. Destroying a session also:
* Removes the in-progress marker from the associated issue (the `AI-Working` label on Linear, or `Implementing` status on Jira)
* Clears it from the deduplication window, so the orchestrator can pick it up again on the next poll
If a Fly Machine appears stuck and is not progressing, destroying it from the sessions panel is the cleanest recovery path.
### Reaper
The reconciliation-sweep dashboard.
The top of the page hosts the **runner mode toggle** (`default` / `gha` / `fly` / `shadow`).
If the `RUNNER_MODE` environment variable is set on the orchestrator process, it takes precedence over this database value and the UI flags that an env-var lock is active.
A summary card shows the 24-hour total of machines and jobs the reaper destroyed, broken down by rule:
* `orphan`
* `stale-terminal-job`
* `max-age-exceeded`
* `issue-terminal`
Plus the last sweep timestamp.
A recent-actions table lists the latest destructions with:
* Timestamp
* Rule matched
* Machine ID
* Tenant
* Associated issue
* Age at destruction (in seconds)
* `dry-run` or `destroyed` badge (indicating whether the action was a no-op or executed)
If you change runner mode via the UI or API while `RUNNER_MODE` is set in the environment, the new value is persisted to the database but has no effect until the env var is removed and the orchestrator is restarted.
### Secrets
The dedicated Secrets sidebar item is not yet active — it shows a placeholder page. Secret management is split between the [Settings panel](#settings) and the [Projects panel](#projects-team%2Frepo-mappings).
* **Per-team secrets** — each project row in the Projects panel has a **Secrets** button that opens an inline form. Secrets are stored as Fly app secrets prefixed by the team key (for example, a secret named `MY_TOKEN` for project `ENG` is stored as `ENG_MY_TOKEN`). Secret names must contain only letters, digits, and underscores.
* **Global secrets** — listed, created, and deleted from the Settings panel. Global secrets are Fly app secrets injected into every session machine and are not scoped to any specific project. Their names must not start with any project key prefix.
### Settings
The Settings panel has two sections: Fly sessions infrastructure and global machine secrets.
**Fly Sessions App**
* **`flySessionsApp`** — the Fly.io app name used for Fly Machine sessions.
* **`flySessionsRegion`** — the default region for new Fly Machine sessions.
Both values can be overridden at the environment level via `FLY_SESSIONS_APP` and `FLY_SESSIONS_REGION`. When an env override is active, the UI shows the runtime value alongside the database value and flags that the env var is winning.
Changes to the sessions app or region that differ from the running process take effect after a restart.
**Global Machine Secrets**
The Settings panel is also where you manage global Fly app secrets — values injected into every session machine as environment variables. Use this for credentials shared across all projects. Per-project secrets are managed from each project row in the [Projects panel](#projects-team%2Frepo-mappings).
Global secret names must contain only letters, digits, and underscores, and must not start with any project key prefix.
## Developer
### Audit log
Shows the dispatch-deduplication ledger for the last 24 hours.
Each row includes:
* Issue identifier and title
* When the issue was dispatched
* A delete button to remove it from the dedup window
Issues are deduplicated for 24 hours after dispatch to prevent the orchestrator from picking up the same issue repeatedly. The dedup panel shows every issue currently in the dedup window.
You can manually remove an issue from the dedup window if you want the orchestrator to re-dispatch it before the 24-hour window expires.
The roadmap calls for richer audit-log content here over time; the current implementation is focused on the dedup window.
### Customizations
Lists every file under the `custom/` directory in the orchestrator's working tree that overrides a built-in.
The table shows each file's:
* Path
* Category (`pipeline` / `step` / `provider` / `other`)
* Status (`override` / `additive` / `—` for the `other` category)
* Upstream counterpart path it shadows
* File size
* Last-modified time
A CI workflow (`protect-custom.yml`) flags upstream PRs that modify files under `custom/` outside the allowed paths (`custom/README.md` and `.gitkeep` files). The check is currently **advisory** — it won't hard-block a merge but will surface a warning in CI. The team has it tracked to restore as a hard fail.
See [Add custom pipeline steps](/customize/custom-steps) for the resolution rules.
***
## Admin API reference
All `/api/*` endpoints except `/api/auth` require a `Bearer` token obtained from `/api/auth`. Tokens expire after 24 hours.
### Authentication
POST your access code to `/api/auth`:
```bash theme={null}
curl -s -X POST https://your-orchestrator/api/auth \
-H "Content-Type: application/json" \
-d '{"code": "your-access-code"}' \
| jq -r '.token'
```
The response contains a `token` field. Store it for subsequent requests.
Include the token as a `Bearer` header:
```bash theme={null}
TOKEN=""
curl -s https://your-orchestrator/api/mappings \
-H "Authorization: Bearer $TOKEN"
```
### Endpoint reference
| Method | Path | Description |
| -------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| `POST` | `/api/auth` | Authenticate with access code; returns bearer token |
| `GET` | `/api/mappings` | List all project mappings |
| `POST` | `/api/mappings` | Create or update a project mapping |
| `PATCH` | `/api/mappings/:teamKey` | Update a mapping's concurrency cap (`maxInProgressAiIssues`) or paused state (`paused`) |
| `DELETE` | `/api/mappings/:teamKey` | Delete a mapping |
| `POST` | `/api/mappings/:teamKey/sync-workflows` | Re-sync workflow templates from the orchestrator into the target repo. |
| `POST` | `/api/jira/validate-jql` | Validate a JQL clause against a Jira instance before saving |
| `GET` | `/api/jira/fields` | List available Jira custom fields |
| `GET` | `/api/jira/field-options` | List options for a Jira select field |
| `GET` | `/api/log` | Dispatch audit log (last 500 entries) |
| `GET` | `/api/jobs/:jobId/steps` | Get step-by-step execution status for a specific job |
| `GET` | `/api/issues` | List AI-Implement issues across all configured project mappings |
| `GET` | `/api/pulls` | List bot-opened pull requests tracked by the orchestrator |
| `GET` | `/api/blockers` | List issues currently blocked from dispatch, with reason |
| `GET` | `/api/sessions` | List active Fly Machine sessions |
| `DELETE` | `/api/sessions/:machineId` | Destroy a session and reset the associated issue |
| `GET` | `/api/reaper/summary` | 24-hour reaper destruction summary, broken down by rule |
| `GET` | `/api/reaper/recent` | List recent reaper destruction actions |
| `GET` | `/api/dedup` | List issues in the 24-hour dedup window |
| `DELETE` | `/api/dedup/:issueId` | Remove an issue from the dedup window |
| `GET` | `/api/runner-mode` | Get current runner mode |
| `POST` | `/api/runner-mode` | Set runner mode |
| `GET` | `/api/settings` | Get orchestrator settings |
| `POST` | `/api/settings` | Update orchestrator settings |
| `GET` | `/api/global-secrets` | List global Fly secrets |
| `POST` | `/api/global-secrets` | Set a global Fly secret |
| `DELETE` | `/api/global-secrets/:name` | Delete a global Fly secret |
| `GET` | `/api/mappings/:teamKey/secrets` | List per-team Fly secrets |
| `POST` | `/api/mappings/:teamKey/secrets` | Set a per-team Fly secret |
| `DELETE` | `/api/mappings/:teamKey/secrets/:name` | Delete a per-team Fly secret |
| `GET` | `/api/customizations` | List files under `custom/` that override built-ins |
| `GET` | `/api/pipelines-steps` | List pipeline definitions and step modules with override status |
| `GET` | `/api/admin/config-status` | Get environment-status checks (ticketing connection, runner callback, gap-fill trigger) |
| `GET` | `/api/admin/template-status` | Get workflow-template staleness status per target repo |
`/api/auth` is the only endpoint that does not require a bearer token. All other `/api/*` routes return `401 Unauthorized` if the token is missing or expired.