Skip to main content
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.
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:
See Environment variables for the full list, including 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.
Either mode reads .env from the project root on startup, and 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:
Add ADMIN_ACCESS_CODE and any notification variables if needed.
4

Deploy the app

​
Fly.io infrastructure details

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