Runners
Registering, monitoring, and managing Runner execution agents.
Runners
Runners are the execution agents that run Terraform on behalf of users. The Runners page manages their lifecycle. For how Runners work internally, see the Runner Agent documentation.
Runners Page
Located at /dashboard/runners, showing:
Status Filters
- All, ONLINE, OFFLINE, DRAINING
Search
Filter by Runner name.
Data Table
| Column | Description |
|---|---|
| Name | Runner identifier |
| Type | cloud-hosted or self-hosted |
| Region | AWS region (cloud-hosted only) |
| Status | Badge: ONLINE (green), DRAINING (yellow), OFFLINE (red) |
| Version | Runner release version |
| Created | Registration timestamp |
| Actions | Deploy, update, remove buttons |
Active Jobs Section
A separate table showing jobs currently assigned to Runners (QUEUED, CLAIMED, or PROCESSING).
Update Alert
If outdated Runners are detected (version < latest release), an alert appears with an "Update All" button that queues UPDATE_WORKER jobs for each outdated Runner.
Adding a Runner
Click "Add Runner" to open the registration sheet with two tabs:
Provisions a Runner automatically in ECS Fargate:
- Select a cloud identity and region
- Click Deploy → queues a
DEPLOY_WORKERjob - The job provisions: ECS task definition, IAM roles, CloudWatch log group, security groups
- After ~2 minutes, the Runner appears as ONLINE
Cloud-hosted Runners support scale-to-zero — they shut down when no jobs are queued and restart automatically when needed.
For running a Runner on your own infrastructure:
- Enter a name for the Runner
- Click Register → generates a
worker_idandworker_token - Copy the credentials (shown once, never stored in plaintext)
- Set the environment variables on your machine and run the Runner binary
See Self-Hosted Mode for full setup instructions.
The worker token is shown only once at registration. If lost, the Runner must be re-registered. See Authentication Flows for how token verification works.
Status Indicators
Status is determined by heartbeat recency:
| Status | Meaning | Heartbeat |
|---|---|---|
| ONLINE | Ready to accept jobs | Within last 60 seconds |
| DRAINING | Finishing current job, not accepting new ones | Sent with DRAINING flag |
| OFFLINE | Missed heartbeat, jobs will be requeued | > 60 seconds ago |
Real-time Updates
The Runners page subscribes to workers table changes and provision_jobs changes via Supabase Realtime. Status changes, new registrations, and job assignments appear instantly.
Version Tracking
Each Runner reports its version on heartbeat. The page shows:
- Current version per Runner
- Latest available version (from
worker_releasestable) - Release Notes dialog showing the changelog for each version
When a new Runner release is published via the CI pipeline, existing cloud-hosted Runners are updated via UPDATE_WORKER jobs that trigger ECS force-new-deployment.