Skip to main content
The orchestrator is a Node.js service that polls Linear, 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.
1

Clone the repository

2

Configure environment variables

Open .env and fill in at minimum the three required variables:
See Environment variables below for the full list.
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.
.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.
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.
If ADMIN_ACCESS_CODE is not set, the admin UI is disabled entirely.

​
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.
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, copy the example client config and create resources manually:
3

Set Fly secrets

The orchestrator reads its credentials from Fly secrets at runtime:
Add ADMIN_ACCESS_CODE and any notification variables if needed.
4

Deploy the app

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

​
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

​
Environment variables

The table below covers all variables the orchestrator reads. Required variables must be set before the service will start successfully. See Environment variables for AI-Implement for more detailed information on each variable.
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.

​
What’s next

Connect a target repo

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

Environment variables reference

Full reference for every environment variable the orchestrator supports.