Skip to main content
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

Use Node.js 24.x for local development. Running locally lets you test a configuration before 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.
1

Clone the repository

2

Configure environment variables

Open .env and fill in the GitHub App credentials plus your ticketing provider’s. For Linear that is:
For the managed Codex path, also set ADMIN_ACCESS_CODE (or configure sign-in), a stable RUNNER_TOKEN_SECRET, and RUNNER_CALLBACK_BASE_URL. The callback URL must be a public HTTPS base URL reachable from GitHub Actions; a hosted job cannot reach your local localhost address. Planning refuses dispatch without the callback URL and secret.Keep RUNNER_TOKEN_SECRET stable: changing it makes stored model credentials unreadable. See Environment variables for these settings and the Jira equivalents.
3

Install dependencies

4

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:
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 and npm run dev:local load .env automatically when it exists. Edit the file before starting, and restart the process after changing it.For configured Codex smoke runs, use the local Codex procedure. Managed post-push review-fix support uses GitHub Actions and a healthy Restate connection; see Managed review-fix with Codex.
Either mode starts the polling loop and HTTP server on port 8080.
5

Verify it is running

Check the health endpoint:
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.
1

Install the Fly CLI and log in

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

Provision a new client

The scripts/provision-client.sh script walks you through creating a new Fly app interactively:
Alternatively, create the resources yourself:
The script signs off by suggesting you commit the clients/<slug>.toml it wrote and push to deploy. That deploys nothing — the file is ignored by git and nothing reads it. Deploy with the step below instead.
3

Set Fly secrets

The orchestrator reads its credentials from Fly secrets at runtime:
For managed Codex accounts, also set a stable RUNNER_TOKEN_SECRET and set RUNNER_CALLBACK_BASE_URL to the app’s public HTTPS base URL. Configure ADMIN_ACCESS_CODE or admin sign-in before adding account credentials. Add notification variables if needed.
4

Deploy the app

​
Fly.io infrastructure details

Each Fly app uses:
  • Machine size: shared-cpu-1x with 2 GB of memory
  • 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.