Setup and registration

Administration → Runners → Setup is the two-step flow for self-hosted agents.

1

Step 1 — Create a runner group

See Groups You must have at least one enabled group before you can generate an install command.

♙
2

Step 2 — Register runners

Select a group, platform, and options, then generate an install command and run it on the host.

›_

Register runners

  1. Select a runner group. The helper text shows the group's scope.
  2. Select a platform: Linux, Windows, Docker, or Kubernetes. See Platforms
  3. For Linux or Windows, choose isolation: Process or Container. Docker and Kubernetes lock isolation automatically.
  4. Optionally set a runner name, name prefix, and labels (not used for Kubernetes YAML identity — the cluster assigns unique names).
  5. Optionally set max uses and token TTL.
  6. Click Generate registration command.
  7. Copy the command and run it on the host.
  8. Refresh Overview. The runner appears when registration and the first heartbeat succeed.

Runner name

Option When to use
Runner name Fixed unique name in this organization.
Runner name prefix Scale replicas: each registration becomes prefix + random suffix (e.g. prod-482913).
Blank Agent uses the host name from the install environment.

Labels at registration

Comma-separated labels are baked into the install command and applied on register. You can edit them later from Overview. Do not assign axio-\* to self-hosted runners. See Labels

After the command is ready

The page shows:

✓ Execution profile (e.g. Linux · Process)
✓ Token prefix, expiry, max uses, group, labels
✓ System / network prerequisites
✓ Copyable install script for the selected platform
i

You can switch the platform cards to view the Linux vs Docker vs Kubernetes variant of the same token when instructions exist for those platforms. Register another one starts a new token so two hosts do not share identity.

Token options

Field Default Limit
Max uses Unlimited until expiry (static fleet token) 1 – 10000
Token TTL Shown in the generated instruction (often 60 minutes if unset) 1 – 43200 minutes (30 days)

Leave max uses blank for a long-lived install token you reuse across a static fleet. Set max uses to 1 for a single machine. For Docker/Kubernetes replicas, set max uses ≥ replica count.

After generate you can Revoke token so the command stops working. Historical revoked or obsolete tokens can be cleaned without affecting the command you just copied. See Tokens

What happens on the host

›_ configure / docker run / kubectl apply
↓
API POST /runner-agent/register (axreg_\* token)
↓
● Runner row created + long-lived axrun_\* token stored on the host
↓
♥ Heartbeat + poll for work
↓
♧ Row appears on Overview

The registration token is discarded after exchange. The agent keeps the long-lived token in config (mode 0600) or the encrypted credential store.

Control plane URL

Install commands embed API_PUBLIC_URL (must include /api/v1). If registration returns HTML or HTTP 405, the URL is the web UI, not the API. Fix ingress or the public API URL, then generate a new command.

i

From a Docker runner on the same host as the API, use http://host.docker.internal:3001/api/v1. Machine-mode on the same VM can use http://localhost:3001/api/v1.

Local quick start

bash
npm run build:runner

cd runner/installer

./configure.sh --url http://localhost:3001/api/v1 --token axreg_... --name my-runner

./run.sh