Self-Hosted Runners

Manage self-hosted runners for scanning private infrastructure.

Why Self-Hosted Runners?

Self-hosted runners allow you to:

• Scan infrastructure behind a firewall
• Access private networks and VPCs
• Use cloud-native authentication (AWS Instance Profile, Azure Managed Identity)
• Use your own compute resources
• Maintain data sovereignty

Supported Platforms

Platform	Authentication	Labels
AWS EC2	Instance Profile, Assume Role	aws
Azure VM	Managed Identity	azure
GCP VM	Workload Identity	gcp

List Runners

View all configured runners:

controlinfra runners list

Output:

┌──────────┬─────────────────┬─────────┬────────────────┬─────────────┐
│ ID       │ Name            │ Status  │ Labels         │ Last Seen   │
├──────────┼─────────────────┼─────────┼────────────────┼─────────────┤
│ a1b2c3d4 │ prod-runner     │ online  │ aws, prod      │ 30s ago     │
│ e5f6g7h8 │ staging-runner  │ online  │ aws, staging   │ 1 min ago   │
│ i9j0k1l2 │ dev-runner      │ offline │ local          │ 2 days ago  │
└──────────┴─────────────────┴─────────┴────────────────┴─────────────┘

Create a Runner

Register a new runner:

controlinfra runners add prod-runner

Output:

✓ Runner "prod-runner" created

┌──────────────────────────────────────────────────────────┐
│ Runner Created                                            │
├──────────────────────────────────────────────────────────┤
│ ID:      a1b2c3d4e5f6                                     │
│ Name:    prod-runner                                      │
│ Token:   ctrl_runner_abc123xyz...                         │
└──────────────────────────────────────────────────────────┘

Setup Instructions:
────────────────────────────────────────────────────────────

1. Get the installation script:
   controlinfra runners setup a1b2c3d4e5f6

2. Or manually install the runner agent on your server

Options

Option	Description	Default
[name]	Runner name (positional)	my-runner
--labels <labels>	Comma-separated labels	-

# AWS runner with labels
controlinfra runners add prod-runner --labels aws,production,us-east-1

# Azure runner with labels
controlinfra runners add azure-runner --labels azure,production,eastus

Cloud Labels

Use aws or azure labels to help organize runners by cloud provider. The UI will group runners by these labels automatically.

Get Installation Script

Get the script to install a runner on your server:

controlinfra runners setup <runner-id>

Linux/macOS

controlinfra runners setup a1b2c3d4

Output:

  Runner Setup

────────────────────────────────────────────────────────────

Installation Script (Linux/macOS):

# Download and install runner
curl -fsSL https://controlinfra.com/install-runner.sh | \
  RUNNER_TOKEN="ctrl_runner_abc123..." \
  RUNNER_NAME="prod-runner" \
  API_URL="https://controlinfra.com" bash

# Or using Docker:
docker run -d \
  --name controlinfra-runner \
  -e RUNNER_TOKEN="ctrl_runner_abc123..." \
  -e API_URL="https://controlinfra.com" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  controlinfra/runner:latest

────────────────────────────────────────────────────────────

Keep the token secure - it provides access to your account.

Windows

controlinfra runners setup a1b2c3d4 --os windows

Check Runner Status

Get detailed status of a runner:

controlinfra runners status <runner-id>

Output:

┌──────────────────────────────────────────────────────────┐
│ Runner Status                                             │
├──────────────────────────────────────────────────────────┤
│ ID:          a1b2c3d4e5f6                                 │
│ Name:        prod-runner                                  │
│ Status:      online                                       │
│ Labels:      aws, production                              │
│ Version:     1.2.0                                        │
│ Last Seen:   30 seconds ago                               │
│ Created:     5 days ago                                   │
└──────────────────────────────────────────────────────────┘

Recent Jobs:
  ✓ myorg/infrastructure (2 min ago)
  ✓ myorg/terraform-modules (15 min ago)
  ✗ myorg/legacy-infra (1 hour ago)

Regenerate Token

If a token is compromised, regenerate it:

controlinfra runners token <runner-id>

Output:

✓ Token regenerated

New Token: ctrl_runner_xyz789...

Update your runner configuration with this new token.
The old token is now invalid.

WARNING

After regenerating, you must update the token on your runner agent or it will stop working.

Update a Runner

Update runner details:

controlinfra runners update <runner-id>

Options

Option	Description
--name <name>	New runner name
--description <text>	Runner description
--labels <labels>	Comma-separated labels

controlinfra runners update a1b2c3d4 --name new-runner-name --labels aws,production

Output:

✓ Runner "new-runner-name" updated

Mark Runner Offline

Mark a runner as offline:

controlinfra runners offline <runner-id>

Output:

✓ Runner marked as offline

Remove a Runner

Delete a runner:

controlinfra runners remove <runner-id>

You'll be prompted to confirm. Use --force to skip:

controlinfra runners remove <runner-id> --force

Using Runners for Scans

Specify a runner when triggering a scan:

controlinfra scan run owner/repo --runner prod-runner

Docker Deployment

The recommended way to run a self-hosted runner:

docker run -d \
  --name controlinfra-runner \
  --restart unless-stopped \
  -e RUNNER_TOKEN="your-token" \
  -e API_URL="https://controlinfra.com" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.aws:/root/.aws:ro \
  controlinfra/runner:latest

Environment Variables

Variable	Description	Required
RUNNER_TOKEN	Runner authentication token	Yes
API_URL	Controlinfra API URL	Yes
RUNNER_NAME	Override runner name	No
RUNNER_LABELS	Additional labels	No

Next Steps

• Self-Hosted Runners Guide - Detailed setup for AWS and Azure
• AWS Credentials - AWS IAM configuration
• Azure Credentials - Azure authentication setup
• Integrations - Slack, AWS, AI setup
• Scans - Running scans with runners