neo runner
Manage this host as a self-hosted runner
neo runner [OPTIONS] <COMMAND>neo runner register
Section titled “neo runner register”Register this machine as a runner (embedded agent — no separate install).
Zero-arg inside a pushed checkout with a stored login; defaults to actor-bound: it only claims jobs from runs you triggered. Credentials persist to ~/.config/neosource/runner.json.
neo runner register [OPTIONS]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
--scheduler |
<SCHEDULER> |
no | Scheduler base URL. Default: inferred from this checkout’s neosource or origin remote — the two names neo push writes — then --host, then the stored login |
|||
--auth-token |
<AUTH_TOKEN> |
no | NEOSOURCE_RUNNER_AUTH_TOKEN |
Bootstrap PAT for the registration call. Default: the stored neo auth login credential (or NEOSOURCE_TOKEN) |
||
--enroll |
<ENROLL> |
no | NEOSOURCE_RUNNER_ENROLL_TOKEN |
Register with a runner-enrollment token (nse_…) from neo runner enroll create instead of your login. No login is needed: the enrollment decides the workspace, whether the runner is actor-bound or workspace-wide and whether it is a session runner, and --vm-backend must be one it allows. The token is used once and never written to disk; this machine keeps a node id beside its credentials, so enrolling it again replaces its previous runner. An enrolled runner whose registration is revoked stops and asks to be enrolled again |
||
--labels |
<LABELS> |
no | self-hosted,linux,x64 |
Comma-separated labels this runner advertises. See docs/runner/labels.md | ||
--serve-default-labels |
no | Also advertise the hosted default labels (ubuntu-latest, ubuntu-24.04, ubuntu-22.04) so unmodified workflows can run on this machine |
||||
--workspace-wide |
no | Claim ANY job in the workspace, not just runs you triggered. Requires workspace admin (server-enforced). Default is actor-bound: only jobs from runs YOU triggered (your pushes, PRs, manual dispatches) | ||||
--workspace-id |
<WORKSPACE_ID> |
no | Workspace to bind to. Default: inferred from a checkout remote pointing at the scheduler | |||
--vm-backend |
<VM_BACKEND> |
no | docker_shell |
VM backend reported to the scheduler (docker_shell runs step containers via the host docker daemon) |
||
--state-dir |
<STATE_DIR> |
no | Where runner credentials are persisted. Defaults to $XDG_CONFIG_HOME/neosource or ~/.config/neosource |
|||
--name |
<NAME> |
no | Display name shown in the web UI and neo runner list. Default: this machine’s hostname. Remembered in runner.json until you pass another; --name "" forgets it and goes back to the hostname |
neo runner start
Section titled “neo runner start”Start the long-poll claim loop.
Registers first if this machine has no persisted runner credentials yet.
neo runner start [OPTIONS]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
--scheduler |
<SCHEDULER> |
no | Scheduler base URL. Default: inferred from this checkout’s neosource or origin remote — the two names neo push writes — then --host, then the stored login |
|||
--auth-token |
<AUTH_TOKEN> |
no | NEOSOURCE_RUNNER_AUTH_TOKEN |
Bootstrap PAT for the registration call. Default: the stored neo auth login credential (or NEOSOURCE_TOKEN) |
||
--enroll |
<ENROLL> |
no | NEOSOURCE_RUNNER_ENROLL_TOKEN |
Register with a runner-enrollment token (nse_…) from neo runner enroll create instead of your login. No login is needed: the enrollment decides the workspace, whether the runner is actor-bound or workspace-wide and whether it is a session runner, and --vm-backend must be one it allows. The token is used once and never written to disk; this machine keeps a node id beside its credentials, so enrolling it again replaces its previous runner. An enrolled runner whose registration is revoked stops and asks to be enrolled again |
||
--labels |
<LABELS> |
no | self-hosted,linux,x64 |
Comma-separated labels this runner advertises. See docs/runner/labels.md | ||
--serve-default-labels |
no | Also advertise the hosted default labels (ubuntu-latest, ubuntu-24.04, ubuntu-22.04) so unmodified workflows can run on this machine |
||||
--workspace-wide |
no | Claim ANY job in the workspace, not just runs you triggered. Requires workspace admin (server-enforced). Default is actor-bound: only jobs from runs YOU triggered (your pushes, PRs, manual dispatches) | ||||
--workspace-id |
<WORKSPACE_ID> |
no | Workspace to bind to. Default: inferred from a checkout remote pointing at the scheduler | |||
--vm-backend |
<VM_BACKEND> |
no | docker_shell |
VM backend reported to the scheduler (docker_shell runs step containers via the host docker daemon) |
||
--state-dir |
<STATE_DIR> |
no | Where runner credentials are persisted. Defaults to $XDG_CONFIG_HOME/neosource or ~/.config/neosource |
|||
--name |
<NAME> |
no | Display name shown in the web UI and neo runner list. Default: this machine’s hostname. Remembered in runner.json until you pass another; --name "" forgets it and goes back to the hostname |
neo runner list
Section titled “neo runner list”List the runners you can see.
Without --org: your personal runners in every workspace, plus every runner in your personal workspace. With --org: that organization’s runners — all of them for an admin or owner; for a member, the shared (workspace-bound) runners plus your own. Each line shows the short id, name, status (idle / busy / offline), binding (@handle for a personal runner, shared for a workspace-bound one, (session) for a neo push --runner session), workspace, labels, the reported machine (unknown for an agent too old to report it) and when it last polled.
neo runner list [OPTIONS]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
--org |
<SLUG> |
no | List this organization’s runners instead of your own | |||
--json |
no | Print the server’s JSON response instead of one line per runner |
neo runner cache
Section titled “neo runner cache”Show a direct-VM runner’s capacity and cache disks.
RUNNER is a full runner id, a unique id prefix or a unique name among the runners neo runner list shows (with --org, that organization’s list). Prints the capacity the runner last reported with a claim (memory in MiB and vCPUs, free over budget; never reported for a runner that is not a Cloud Hypervisor direct-VM runner, or an agent too old to report it), totals over the listed disks, and one line per cache disk: key, repository, job and matrix leg, state (committed or absent), generation, warm runs over runs and when a job last used it. Disks of repositories you cannot read are omitted, and so are their runs from the totals. A hosted runner’s cache is visible to site admins only.
neo runner cache [OPTIONS] <RUNNER>| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<RUNNER> |
yes | The runner: full id, unique id prefix or unique name | ||||
--org |
<SLUG> |
no | Resolve RUNNER among this organization’s runners instead of your own | |||
--json |
no | Print the server’s JSON response instead of the report |
neo runner enroll
Section titled “neo runner enroll”Create, list and revoke runner enrollment tokens.
An enrollment token (nse_…) registers runners from a fixed template — workspace, actor-bound or workspace-wide, allowed VM backends, session or standing — so a machine never holds your login or a personal access token: ns-runner start --enroll <token> or neo runner start --enroll <token>. These commands need NEOSOURCE_TOKEN set to a personal access token or workspace service token that carries workspace:write; with only the neo auth login credential they print the settings page where enrollments are managed and exit non-zero. An enrollment keeps working only while its creator still holds the permission it needed and, when a token created it, while that token is live.
neo runner enroll [OPTIONS] <COMMAND>neo runner enroll create
Section titled “neo runner enroll create”Create an enrollment token; it is printed once.
Default: actor-bound runners (they only claim runs you triggered; workspace membership suffices) in your personal workspace, the docker_shell backend, one use, valid for one hour.
neo runner enroll create [OPTIONS]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
--org |
<SLUG> |
no | Enroll runners into this organization instead of your personal workspace | |||
--workspace-wide |
no | Runners claim ANY job in the workspace, not just runs you triggered. Requires workspace admin | ||||
--local |
no | Register local (developer machine) runners instead of self_hosted ones |
||||
--vm-backend |
<BACKEND> |
no | docker_shell |
A VM backend registrations may choose; repeat for several (docker_shell, cloud_hypervisor, k8s_runc) |
||
--ephemeral |
no | Register session runners (neo push --runner style), which are removed when their session ends |
||||
--max-uses |
<MAX_USES> |
no | 1 |
Registrations the token admits, 1–1000. Re-registering a machine uses one too | ||
--expires |
<EXPIRES> |
no | 1h |
How long the token works: a number and a unit, s, m, h or d (30m, 7d); at most 30 days |
||
--json |
no | Print the server’s JSON response (it carries the token) |
neo runner enroll list
Section titled “neo runner enroll list”List the enrollments you may manage.
A workspace admin sees every enrollment of the workspace; a member sees their own actor-bound ones. Each line shows the id, binding, scope, allowed backends, uses and when it expires or was revoked.
neo runner enroll list [OPTIONS]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
--org |
<SLUG> |
no | List this organization’s enrollments instead of your personal workspace’s | |||
--json |
no | Print the server’s JSON response |
neo runner enroll revoke
Section titled “neo runner enroll revoke”Revoke an enrollment, or remove one machine it registered.
Without flags the token stops working and runners it registered keep running. A deregistered runner’s running job goes back to the queue.
neo runner enroll revoke [OPTIONS] <ENROLLMENT_ID>| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<ENROLLMENT_ID> |
yes | The enrollment id (neo runner enroll list) |
||||
--org |
<SLUG> |
no | The enrollment’s organization, when it is not in your personal workspace | |||
--cascade |
no | Also deregister every runner registered through it | ||||
--node |
<NODE_ID> |
no | Deregister only the runner of this machine (its node id, shown by neo runner list) and keep the enrollment |
|||
--json |
no | Print the server’s JSON response |