> ## 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.
**Experimental version.**
This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the [latest stable version here](/introduction).
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](/latest/configuration/team-repo-mappings) for the full field reference and defaults.
**New in latest:**
* The Projects stepper exposes three optional **run-cap** fields — `maxTurns`, `maxIterations`, and `maxJobMinutes` — in the Capacity step. Tune these per project to control cost and reliability.
* The **Default Branch** field is now required. Use the repository's actual primary branch (commonly `main`, `master`, or `development`).
#### 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 the **target repo's** **GitHub Owner**, **Repository Name**, and **Default Branch**.
Default Branch is required and must match the repo's actual primary branch (commonly `main`, `master`, or `development`).
Runner, Provider, Capacity, Secrets, and Review steps follow. For a first run, defaults are reasonable.
The **Capacity** step exposes three optional run-cap fields:
| Field | Default if blank | Purpose |
| --------------- | ------------------------ | ------------------------------------------------------ |
| `maxTurns` | 50 | Maximum Claude conversation turns per run |
| `maxIterations` | Bedrock: 2, Anthropic: 3 | Maximum feedback-loop iterations per run |
| `maxJobMinutes` | 90 | Wall-clock timeout before forced termination (minutes) |
Leave any field blank to use the default. Setting these tighter than the defaults is the recommended way to control cost and reliability per project.
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](/latest/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
#### Per-team secrets
Each project mapping has its own per-team secrets at `/api/mappings/:teamKey/secrets`.
Secrets are stored as Fly app secrets with the team key as a prefix (e.g. 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
Global secrets are Fly app secrets that do not belong to any specific project mapping. They are listed, created, and deleted from `/api/global-secrets`.
Global secret names must not start with any project key prefix (to keep the per-team scoping unambiguous).
### Settings
The settings panel manages orchestrator-level configuration:
* **`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 settings that differ from the running process take effect after a restart.
## 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](/latest/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.
### Runner callback endpoints
Two endpoints sit outside the `/api/*` namespace and are called by **runners** (GitHub Actions workflow jobs, Fly Machine sessions, or local Docker containers running an issue), not by operators. They use a separate authentication scheme from the bearer tokens above.
| Method | Path | Purpose |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/runner/result` | Reports the final outcome of a dispatch — success or failure, PR URL when one was opened, error context when not. The token is **single-use**: once consumed, the dispatch result is locked in and the endpoint rejects further calls for that dispatch. |
| `POST` | `/runner/progress` | Streams step-by-step progress updates throughout a run (each pipeline step's status, elapsed time, and any structured output). The token is **multi-use** so the runner can post many updates during a single dispatch; consumed independently of the result token. |
Both endpoints respond `501 Not Implemented` when the orchestrator has no `RUNNER_TOKEN_SECRET` configured, since neither can validate tokens without it.
Operators do not normally call these directly. They're documented here so that monitoring tools, ingress configurations, and debugging sessions can account for runner-side traffic correctly.
### Webhook and trigger endpoints
Two endpoints sit outside the operator API but are operator-configurable: you set their URLs and secrets in your target repos (or at the organization level), and the orchestrator validates incoming requests against those secrets. Documented here so monitoring tools, ingress rules, and integration testing can account for the routes.
| Method | Path | Purpose |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/api/github/webhook` | Receives GitHub webhook events from your target repos — pull request reviews, review comments, issue comments, and pull request merges. Validates the HMAC signature against `GITHUB_WEBHOOK_SECRET`. Returns `503` when the secret is unset (endpoint disabled). |
| `POST` | `/trigger/gap-fill` | Called by `comment-trigger.yml` in your target repo when a user comments `/ai-implement` on a PR. Validates a bearer token equal to `GAP_FILL_TRIGGER_SECRET`. Dispatches a gap-fill run for the PR. Returns `503` when the secret is unset (trigger disabled). |
Both endpoints require their corresponding secret to be configured on the orchestrator.
See [`GITHUB_WEBHOOK_SECRET`](/latest/configuration/environment-variables#param-github-webhook-secret) and [`GAP_FILL_TRIGGER_SECRET`](/latest/configuration/environment-variables#gap-fill-trigger)