Environment variables for AI-Implement

The AI-Implement orchestrator is configured entirely through environment variables. Variables fall into three contexts depending on where you configure them:

On the orchestrator service itself
As GitHub Actions secrets on the orchestrator’s own repo (for CI auto-deploy)
As GitHub Actions secrets on each target repo (read by the synced workflow files when Claude runs).

A few credentials are needed in more than one context, though only one pair changes names between contexts:

On the orchestrator: GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY
On each target repo: AI_IMPLEMENT_APP_ID and AI_IMPLEMENT_PRIVATE_KEY

These both refer to the same GitHub app’s credentials. Nothing else is renamed across contexts. The variables are read at startup; restart the app after changing them. Pick the tab that matches where you’re configuring right now.

Orchestrator runtime
GitHub Actions CI (orchestrator repo)
Target-repo workflow secrets

Variables the AI-Implement Node service reads at startup.

For local development, set on the orchestrator’s .env file.
For Fly.io deployment, set on the Fly.io app via fly secrets set (for sensitive values) or in fly.toml’s [env] block (for non-sensitive defaults).

Required

The orchestrator needs the GitHub App credentials plus at least one ticketing provider’s credentials to start.

string

required

Numeric ID of the GitHub App the orchestrator uses to authenticate with GitHub and dispatch workflows. Find this on the app’s settings page under General → App ID.

string

required

RSA private key (PEM format) for the GitHub App, used to generate installation tokens. When passing this as an environment variable, newlines in the PEM file must be replaced with literal \n characters.

The private key PEM file contains real newlines. When you set it as an environment variable (e.g. with fly secrets set), those newlines must be expressed as the two-character sequence \n. Example: "-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----".

Ticketing

The orchestrator can use Linear, Jira, or both. Expand the provider(s) you use:

Linear

string

required

Required when any project mapping uses ticketingProvider: linear.Client ID of the Linear application the orchestrator authenticates as. See Create a Linear app for how to create it.

string

required

Required when any project mapping uses ticketingProvider: linear.Client secret for the same application. Both values remain visible on the application’s settings page, so you can re-copy them whenever you need to.

string

default:"https://linear.app"

User-facing Linear workspace URL, used to render issue links in dispatch logs and comments.

The orchestrator acts as the application itself, not as a person. Every status change, label, and comment it makes is attributed to the app in Linear’s activity feed.

Jira

Both authentication modes need JIRA_TOKEN and JIRA_SITE_URL. Which of the remaining two you set decides the mode.

string

required

Required when any project mapping uses ticketingProvider: jira.Either an Atlassian API token or an OAuth access token, depending on the mode you pick below.

string

required

Required when any mapping uses Jira.User-facing Atlassian site URL, e.g. https://acme.atlassian.net. Renders issue links in dispatch logs and comments, and serves as the API host in Basic auth mode.

string

Selects Basic auth — the recommended mode.The Atlassian account email paired with JIRA_TOKEN. Create the token under Security → API tokens on your Atlassian account.Calls go to JIRA_SITE_URL directly, and the token is long-lived with nothing to refresh.Leave this blank to use OAuth instead.

string

Required only for OAuth mode, meaning when JIRA_EMAIL is blank.Jira Cloud tenant ID, found at https://<your-site>.atlassian.net/_edge/tenant_info under cloudId. Routes calls through api.atlassian.com using short-lived access tokens.Not needed for Basic auth.

Variables beyond this section have defaults or are safely omitted. Set them to override the defaults or to enable optional features.

Service

string

Password for the admin UI at /admin. If this variable is not set, the admin UI is disabled entirely and all /admin and /api/ routes return 503, with a response body naming the missing variable.

string

default:"8080"

HTTP port the orchestrator listens on. The Fly.io internal proxy routes traffic to this port automatically, so you typically do not need to change it.

string

default:"60000"

How often the orchestrator polls for new AI-Implement issues, in milliseconds. Lower values increase ticketing-API usage; values below 10000 are not recommended.

string

default:"/data/dedup.sqlite"

Absolute path to the SQLite file used for deduplication, dispatch logging, and project-mapping storage. Defaults to /data/dedup.sqlite in production (the Fly.io volume mount point) and ./dedup.sqlite when running locally. Change this only if you are mounting the volume at a different path.

string

HMAC-SHA256 secret used to validate incoming GitHub webhook payloads. Set the same value on the GitHub App’s webhook configuration, pointed at https://<orchestrator-host>/api/github/webhook.Leaving it unset disables every webhook-driven behavior: automatic follow-up runs when a reviewer leaves blocking feedback, the faster merge-to-Done path, and — for target repos on the current workflow generation — handling of /ai-implement PR comments. Those repos have no fallback for the comment trigger once this secret is missing, since the orchestrator’s webhook is the only thing listening for it. A poll-based path still moves merged PRs to Done without the webhook, just on a slower cadence.

The webhook also needs the right event subscriptions to deliver anything; see Create a GitHub App.

Notifications

string

default:"slack"

Notification provider to use when a dispatch succeeds or fails. Accepted values: slack (default) or teams. Has no effect if NOTIFY_WEBHOOK_URL is not also set.

string

Incoming webhook URL for the notification provider. Notifications are skipped silently if this variable is unset. For Slack, this is the URL from your Incoming Webhooks app configuration. For Teams, use the connector webhook URL.

Runner mode

string

default:"default"

Global override for runner execution mode. Accepted values:

default (per-mapping setting wins)
gha (force GitHub Actions for all mappings)
fly (force Fly Machines)
local (force local Docker — for local development)
shadow (dispatch via GitHub Actions and additionally boot a Fly Machine for the same run)

shadow is a testing mode. Every run consumes a GitHub Actions job and a Fly Machine, so it roughly doubles Fly session load for as long as it is enabled.

The admin UI’s Reaper page also has a runner-mode toggle, backed by a setting stored in the database. Setting this variable always wins over that toggle — the UI toggle has no effect while the variable is set. To switch modes at runtime from the admin UI, leave this variable unset.

string

Required when RUNNER_MODE=fly or any mapping uses executionMode: fly-machines.Fly.io app name that hosts the session runners.

string

default:"iad"

Default Fly.io region for new session machines.

string

Required when RUNNER_MODE=fly or any mapping uses Fly Machines.Fly API token scoped to the sessions app. Used to create and destroy Fly Machines for runs.

string

default:"ghcr.io/builddownai/ai-implement-runner:latest"

Default container image for runner sessions, in both execution modes. A per-repo .ai-implement/image.yml takes precedence.

string

deprecated

Superseded by AI_IMPLEMENT_RUNNER_IMAGE, which covers both execution modes rather than Fly Machines alone.Still read when the newer variable is unset, and ignored when both are set.

string

default:"ai-implement-runner:local"

Container image to use when RUNNER_MODE=local. Built locally via npm run build:runner:local.

string

default:"http://host.docker.internal:8080"

Base URL the local Docker runner uses to call back to the orchestrator.The default works on native macOS and Windows. Use the host’s own IP on Linux, and on WSL2 use the distro’s IP instead of host.docker.internal (that points at the Windows host, not the distro running the orchestrator).

Runner callbacks (advanced)

These configure how Fly Machine and local-Docker runners authenticate their callbacks to the orchestrator. Defaults are correct for most setups.

string

Public base URL the runner uses to call back to the orchestrator (e.g. https://your-orchestrator.fly.dev). Required for Fly Machines and local Docker runner modes.

string

Secret used to mint and validate short-lived runner-callback tokens. Required when RUNNER_CALLBACK_BASE_URL is set.

Gap-fill trigger

string

Shared bearer secret for the orchestrator’s /trigger/gap-fill endpoint, which starts a gap-fill run against an existing pull request. Leaving it unset disables the endpoint.This is a separate secret from GITHUB_WEBHOOK_SECRET and is not needed for the /ai-implement comment trigger — that path is authenticated by GITHUB_WEBHOOK_SECRET instead (on target repos still running the older, pre-sync workflow generation, it runs inside that repo’s own comment-trigger.yml workflow and needs neither secret). Set GAP_FILL_TRIGGER_SECRET only if you drive gap-fill runs from your own automation.

Reaper (operational)

Controls the reconciliation sweep that cleans up stale Fly Machine sessions.

string

default:"false"

When true, the reaper logs what it would destroy but takes no action. Useful for verifying rules before enabling live cleanup.

string

default:"10"

Number of destructions in a single sweep above which the reaper emits an alert notification (via the configured NOTIFY_TYPE).The count resets on the next pass rather than accumulating over time. Helps catch runaway destruction bugs.

Multi-tenant deploys

Identifiers used when deploying multiple AI-Implement instances as separate Fly apps from a single repo. Most single-client deployments leave these unset.

string

The client identifier matching this app’s clients/<slug>.toml file. Used in logs and notifications to disambiguate multi-tenant deployments.

string

Fly.io app name for this instance. Fly sets this automatically, so you rarely need to. It tags every session machine this instance creates, and the cleanup sweep uses that tag to avoid touching another tenant’s machines — in a shared sessions app, an incorrect value can cause one instance’s cleanup to destroy another tenant’s sessions.

Claude provider forwarding (Fly Machines / local Docker only)

These are read by the orchestrator and forwarded to runner sessions when RUNNER_MODE is fly or local.For GitHub Actions runner mode, the synced workflow uses its own repo secrets directly (see the Target-repo workflow secrets tab); these runtime values are unused.

string

Anthropic API key, forwarded to the runner session as the Claude auth fallback. Required when RUNNER_MODE=fly or local and no OAuth token is configured.

string

Claude Code OAuth token, forwarded to the runner session. Preferred over ANTHROPIC_API_KEY when both are set.

GitHub Actions secrets on the AI-Implement orchestrator’s own repo (not target repos).Used by .github/workflows/deploy-clients.yml for auto-deploy on push to main. Configure under Settings → Secrets and variables → Actions on the orchestrator repo.

string

required

Fly API token used by deploy-clients.yml to run flyctl deploy for each client in clients/*.toml.

Distinct from FLY_SESSIONS_TOKEN (which lives in the orchestrator runtime tab and authorizes session-machine creation, not deploys).

GitHub Actions secrets on each target repo (the repos Claude opens PRs in, not the orchestrator repo). Read by claude-implement.yml, claude-plan.yml, and comment-trigger.yml when the workflows run.Configure under Settings → Secrets and variables → Actions on each target repo (or at the organization level so all target repos inherit them).No ticketing provider secrets belong here. The orchestrator now applies every Linear and Jira update itself, so the synced workflows never read a ticketing credential.

If you added LINEAR_API_KEY, JIRA_TOKEN, JIRA_CLOUD_ID, or JIRA_SITE_URL to a target repo previously, you can remove them.

Secrets

Required

string

required

Numeric ID of the GitHub App AI-Implement uses to authenticate. Same value as the orchestrator’s GITHUB_APP_ID — just named differently as a CI secret.

string

required

GitHub App RSA private key (PEM, with newlines escaped as \n). Same value as the orchestrator’s GITHUB_APP_PRIVATE_KEY.

Claude provider (one provider required)

string

Claude Code OAuth token. Preferred over the API key when present.See Anthropic provider for how to obtain via claude setup-token.

string

Anthropic API key. Used as a fallback when CLAUDE_CODE_OAUTH_TOKEN is not set.

string

Required only when this mapping’s provider is bedrock.IAM role ARN trusted by GitHub OIDC, with bedrock:InvokeModel on your inference profile.

Variables

These are GitHub Actions variables, not secrets — configure under the Variables tab of Settings → Secrets and variables → Actions on the target repo, or at the organization level so all target repos inherit them.

Bedrock

Used so /ai-implement comment-triggered gap-fill runs route to the same provider as orchestrator-initiated runs.

Both variables below are read only by the older, pre-sync comment-trigger.yml workflow. Once a target repo has run Sync workflows, that file is removed and /ai-implement comments are handled by the orchestrator instead — provider and region for those runs come from the project’s mapping in the admin UI, and these variables have no effect.

string

Set to bedrock for Bedrock-backed target repos. Leave unset for the default Anthropic API path.

string

Required when AI_IMPLEMENT_PROVIDER=bedrock.AWS region for Bedrock (e.g. us-west-2).

Gap-fill run caps

Three repository variables cap /ai-implement comment-triggered gap-fill runs the same way per-project caps cap orchestrator-initiated runs. All three are optional — unset means “use the default.”

string

default:"50"

Cap on Claude turns per implement pass. Applies to both Anthropic and Bedrock providers.

string

default:"3 (Anthropic), 2 (Bedrock)"

Cap on implement/review cycles in the feedback loop. The Bedrock default is lower for reliability.

string

default:"90"

Cap on the GitHub Actions job timeout in minutes. GitHub Actions runner mode only.

Setting these here only affects /ai-implement comment-triggered runs on a target repo that has not yet run Sync workflows to move to the current templates — that older comment-trigger.yml workflow is the only thing that reads them. Once a repo syncs, comment-trigger.yml is removed, comment-triggered runs go through the orchestrator, and these variables are silently ignored — the equivalent caps live on the project’s mapping in the admin UI under Configure → Projects for both orchestrator-initiated and comment-triggered runs. See Project mappings for that side.

Runner image

string

Container image used by the GitHub Actions workflow job. When set, overrides the workflow’s built-in default. Useful when you want an organization-level runner image that applies across all your target repos without committing .ai-implement/image.yml to each one.

See Use a custom Fly Machine runner image for the resolution order between this variable and other override mechanisms.

string

Comma-separated list of extra image prefixes the workflows will accept, in addition to the two trusted automatically: ghcr.io/builddownai/ and your own ghcr.io/<owner>/ namespace.A run whose image falls outside every allowed prefix fails at validation before any work starts, so set this whenever you host runner images somewhere else.

Run behavior

string

default:"ubuntu-latest"

The runs-on label for the implementation job. GitHub’s default runners have 2 vCPUs, and the test suites Claude runs are CPU-bound, so a larger-runner label speeds them up noticeably.This selects which runner executes the job, and therefore which machines your repository secrets are exposed to. Point it only at runners you trust.

string

Skills repository as owner/repo, cloned into the workspace so Claude can use its skills during /ai-implement comment-triggered runs.Mirrors the per-project skills setting in the admin UI, which covers orchestrator-initiated runs. Like the gap-fill run caps above, this variable is read only by the older, pre-sync comment-trigger.yml workflow — after a repo runs Sync workflows, comment-triggered runs pick up the skills repo from the project’s mapping instead, and this variable has no effect.

string

default:"summary"

Verbosity of runner logs. Set to stream to get full streaming output, including verbose git tracing on the push step.Any other value, including leaving it unset, gives the condensed summary.

Get Started

Setup

Configuration

Providers

Customize

Reference

Environment variables for AI-Implement

Required

Ticketing

Service

Notifications

Runner mode

Secrets

Required

Claude provider (one provider required)

Variables

Bedrock

Gap-fill run caps

Runner image

Run behavior

​Required

​Ticketing

​Service

​Notifications

​Runner mode

​Secrets

​Required

​Claude provider (one provider required)

​Variables

​Bedrock

​Gap-fill run caps

​Runner image

​Run behavior

Required

Ticketing

Service

Notifications

Runner mode

Secrets

Required

Claude provider (one provider required)

Variables

Bedrock

Gap-fill run caps

Runner image

Run behavior