Deploy the AI-Implement orchestrator

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.

The orchestrator is a Node.js service that polls your ticketing system, dispatches GitHub Actions workflows, and serves the admin UI. You can run it locally during setup or deploy it to Fly.io for persistent production use. Both paths are covered below.

Local development

Running locally is the fastest way to test a configuration before committing to a cloud deployment.

If this is your first time through, start with the quickstart.For the full list of settings the orchestrator reads, see Environment variables.

Clone the repository

git clone https://github.com/BuildDownAI/AI-Implement.git
cd AI-Implement

Configure environment variables

cp .env.example .env

Open .env and fill in the GitHub App credentials plus your ticketing provider’s. For Linear that is:

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
LINEAR_CLIENT_ID=...
LINEAR_CLIENT_SECRET=...

See Environment variables for the full list, including the Jira equivalents.

Install dependencies

npm install

Choose how to run the loop

Both modes run the orchestrator on your machine; they differ in where the implementation jobs run. Pick the one that matches what you want to exercise:

GitHub Actions
Local Docker

npm run dev — implementation jobs are dispatched to run in GitHub Actions. Use this for normal local work on the orchestrator when you’re happy to let jobs run in the cloud.

npm run dev

npm run dev:local — each job runs on your machine as a Docker container, so the whole loop stays local with no dependency on GitHub Actions.

npm run dev:local

Start Docker before you launch it, since the jobs run as Linux containers. The first launch also rebuilds the local runner image, so it takes a little longer than later ones.Because each job is a local container, you can watch one with docker ps and docker logs. Run progress and any failure details still surface in the admin UI (localhost:8080/admin) and on the issue, the same as the other modes.

On Docker Desktop with WSL2, containers resolve host.docker.internal to the Windows host rather than the WSL distro running the orchestrator, so callbacks are refused and runs fail.Set LOCAL_RUNNER_ORCHESTRATOR_URL to the distro’s IP, as you would for a native Linux host.

.env is not auto-loaded. The dev script runs tsx src/index.ts with no dotenv integration, so variables in .env are ignored unless you load them yourself.Either start with tsx --env-file=.env src/index.ts, or export the variables into your shell first with set -a; source .env; set +a before starting the orchestrator.

Either mode starts the polling loop and HTTP server on port 8080.

Verify it is running

Check the health endpoint:

curl http://localhost:8080/

Open the admin UI in your browser at http://localhost:8080/admin. You will be prompted for the ADMIN_ACCESS_CODE value from your .env file.

The admin UI is disabled only when neither ADMIN_ACCESS_CODE nor a sign-in provider is set. The access code is the simpler choice locally — see Set up admin sign-in for the deployed alternative.

Fly.io deployment

For production use, deploy the orchestrator as a Fly.io app. Each client (team or tenant) runs as a separate Fly app defined by a .toml file in the clients/ directory.

Install the Fly CLI and log in

Follow the Fly.io CLI installation guide and run fly auth login.

Provision a new client

The scripts/provision-client.sh script walks you through creating a new Fly app interactively:

./scripts/provision-client.sh <client-slug>

Alternatively, copy the example client config and create resources manually:

cp clients/example-client.toml clients/<slug>.toml
fly apps create <app_name> --org <org>
fly volumes create dedup_data --size 1 --region iad --app <app_name>

Set Fly secrets

The orchestrator reads its credentials from Fly secrets at runtime:

When running on Fly.io, set secrets with fly secrets set rather than committing them in .toml files. The clients/<slug>.toml file should contain only non-sensitive configuration.

fly secrets set \
  GITHUB_APP_ID=123456 \
  GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..." \
  LINEAR_CLIENT_ID=... \
  LINEAR_CLIENT_SECRET=... \
  --app <app_name>

Add ADMIN_ACCESS_CODE and any notification variables if needed.

Deploy the app

Commit your new clients/<slug>.toml and push to trigger an automated deploy, or deploy manually at any time:

fly deploy --remote-only --app <app_name>

Auto-deploy on push (`FLY_API_TOKEN`)

The deploy-clients.yml workflow in the orchestrator repo deploys every client in clients/*.toml on each push to main. It authenticates with a single GitHub Actions secret, FLY_API_TOKEN, set on the orchestrator repo under Settings → Secrets and variables → Actions.

This is not the same token as FLY_SESSIONS_TOKEN. FLY_API_TOKEN is a CI secret used only to run flyctl deploy. FLY_SESSIONS_TOKEN is a runtime environment variable the orchestrator reads to spawn Fly Machine session machines.

Fly.io infrastructure details

Each Fly app uses:

Machine size: shared-cpu-1x with 256 MB of memory — sufficient for the polling loop and admin UI
Volume: A dedup_data volume mounted at /data for SQLite persistence (deduplication, team mappings, and dispatch log)
HTTP service: Internal port 8080, HTTPS enforced, minimum one machine always running

What’s next

Connect a target repo

Sync workflow templates into a GitHub repo and map it to a project in the admin UI.

Environment variables reference

Full reference for every environment variable the orchestrator supports.

Get Started

Setup

Configuration

Providers

Customize

Reference

Deploy the AI-Implement orchestrator

Local development

Fly.io deployment

Auto-deploy on push (`FLY_API_TOKEN`)

Fly.io infrastructure details

What’s next

Connect a target repo

Environment variables reference

​Local development

​Fly.io deployment

​Auto-deploy on push (FLY_API_TOKEN)

​Fly.io infrastructure details

​What’s next

Connect a target repo

Environment variables reference

Local development

Fly.io deployment

Auto-deploy on push (`FLY_API_TOKEN`)

Fly.io infrastructure details

What’s next