# Configuration reference (/reference/configuration)



# 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:

```dotenv
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
```

```dotenv
GITHUB_TOKEN=replace-with-a-token
```

```toml
[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](/concepts/glossary) credentials. Registration
and routing checks require exact agreement between desired group, repositories,
labels, and trust scope.

## Validation and operations

```sh
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.