Configuration reference

Velnor uses separate runner identity, operator configuration, execution backend, and secret files. Packaged Debian installations use the paths below.

Debian files

| File | Purpose | | --- | --- | | /etc/velnor/velnor.env | Non-secret runner, GitHub, scope, label, slot, and resource settings | | /etc/velnor/secrets.env | Operator credentials, mode 0600 | | /etc/velnor/execution.toml | Required backend selection | | /var/lib/velnor | Durable state, runner identity, journals, caches, and release data | | /var/lib/velnor/work | Job workspaces | | /run/velnor | Runtime sockets, health files, and package transaction lock |

The package may migrate a valid GITHUB_TOKEN from velnor.env into secrets.env. Put new credentials directly in the secret file. Tokens never belong in command arguments.

Example:

VELNOR_URL=https://github.com/OWNER/REPO
VELNOR_NAME=velnor
VELNOR_LABELS=self-hosted,velnor,velnor-target-mvp
VELNOR_SLOTS=2
VELNOR_CAPABILITY_VALIDATION=strict

GITHUB_TOKEN=replace-with-a-token

[execution]
backend = "docker"

Use microvm only when Kernel-based Virtual Machine (KVM), verified guest artifacts, jailer, and production guest transport are installed and validated.

Configuration precedence

For the runner identity/config directory, the first available source wins:

1. --config-dir;
2. VELNOR_CONFIG_DIR;
3. systemd STATE_DIRECTORY plus runner;
4. VELNOR_STORAGE_ROOT plus lib/velnor/runner;
5. the XDG state directory plus velnor/runner.

Do not assume $HOME/.velnor. Packaged services use explicit system paths. Configuration directories are private (0700), files are private (0600), and replacements are atomic.

For execution backend configuration, Velnor checks the explicitly configured path, then the config directory, then /etc/velnor/execution.toml. The file must select docker or microvm; missing or invalid selection is an error.

Important settings

| Setting | Meaning | | --- | --- | | VELNOR_URL | Repository, organization, or enterprise target | | VELNOR_NAME | Base runner identity; slots derive unique names | | VELNOR_LABELS | Labels used by GitHub matching | | VELNOR_SLOTS | Concurrent daemon slots | | VELNOR_QUEUE_WAIT_SECS | Maximum wait for an unassigned slot | | VELNOR_CAPACITY_WAIT_SECS | Maximum wait for disk/capacity reservation | | VELNOR_CAPABILITY_VALIDATION | Must be strict | | VELNOR_POOL_ID / VELNOR_POOL_NAME | GitHub runner group selection; a runner group is GitHub's named access-control boundary for runners | | VELNOR_STORAGE_ROOT | Root for Velnor state when not supplied by systemd | | VELNOR_WORK_DIR | Workspace root | | routing_policy_file | Optional exact routing-policy override |

Labels are sorted and deduplicated. Empty labels become self-hosted,velnor. Target-MVP labels add hetzner-sentry-ci, ubuntu-24.04, ubuntu-latest, and velnor-target-mvp; the ARM option adds ubuntu-24.04-arm. macOS labels are rejected; execution is Linux-only.

Scope and registration

Repository scope targets one repository. Organization and enterprise scope requires an explicit runner group; it must not silently use GitHub's Default group. The desired repository/workflow policy is generated locally or supplied through routing_policy_file. Live GitHub membership is evidence, not an implicit allowlist.

Register or configure with velnorctl configure, supplying the GitHub URL, personal access token (PAT), runner name, labels, and, for organization or enterprise scope, pool name/ID. Registration creates per-slot just-in-time (JIT) runner credentials. Registration and routing checks require exact agreement between desired group, repositories, labels, and trust scope.

Validation and operations

velnorctl capabilities export
velnorctl capabilities check JOB_MESSAGE.json
velnorctl preflight --config-dir /etc/velnor --work-dir /var/lib/velnor/work
velnorctl status --json

Capability validation is always strict; bypass or non-strict settings fail startup. Backend preflight also fails if its isolation prerequisites are not available. There is no backend fallback.

Limits

• Configuration and runner identity are private local files; the operator PAT is separate from per-job GitHub credentials.
• VELNOR_SLOTS controls local concurrency, not GitHub scheduling.
• MicroVM supports a narrower action and cache surface than Docker.
• Query, log, and storage projections may be empty after reopening because those operational projections are not fully rehydrated, even though durable event state survives.
• Control/admin mutation routes, diagnostics bundles, and storage maintenance operations are currently unavailable to operators.
• No APT signing-key bootstrap URL or APT repository setup metadata is included in this repository; installation requires a package source provided separately. Fresh package installs remain disabled until configured and started.