CLI

Machine verbs

The kraft admin worker verbs: register, change and remove the machines that run steps, and run a machine's side.

kraft admin worker registers machines and runs their side of the connection. The server, add-on and forge verbs are on their own pages. Every verb here accepts --json; the exceptions are in Output format.

Verbs at a glance

VerbWhat it does
admin worker addRegisters a machine; a dial-in one gets a token. Added in 2.4
admin worker editChanges a machine; the rest stays. Added in 2.4
admin worker enableLets a machine take new steps again. Added in 2.4
admin worker disableTakes no new steps on a machine; running ones finish. Added in 2.4
admin worker rotate-tokenA new token for a dial-in machine. Added in 2.4
admin worker listThe machines, online or offline and why. Added in 2.4
admin worker removeForgets a machine and ends its connection. Added in 2.4
admin worker serveOn a machine: connects to a server. Added in 2.4
admin worker checkOn a machine: what it has for running steps. Added in 2.4
admin worker attachRun by Kraft: a remote step's local process. Added in 2.4
admin worker localRun by the server: the local worker. Added in 2.4

Machines

Added in 2.4

kraft admin worker manages the machines that may run work item steps, listed in workers.yaml. A connected machine runs the steps that work items place on it. Kraft runs admin worker attach itself, as the local process of a step on a machine; you don't run it.

add, edit, enable, disable, rotate-token, list and remove ask the running server, which owns the file. serve and check run on the machine itself.

RefusalCause
403A Kraft session runs add, edit, enable, disable, rotate-token, list or remove.

admin worker add

Added in 2.4

kraft admin worker add [flags] NAME

Registers a machine. NAME is lowercase letters, digits, - and _. A dial-in one prints its token once, then the command to run on it. With --ssh HOST the server connects once and exits 1 if it can't; the machine stays registered.

FlagTypeDefaultMeaning
--sshhost or ssh config aliasnone: the machine dials inA host or ssh config alias for the server to dial.
--capacityintegerthe machine's own limit, else 1The most sessions it may run at once. The lower of this and the machine's own limit applies.
--groupgroup name, repeatablenonePut it in group G, which a step's runner: can name. See Groups. Added in 2.4
--reposrepo IDs, names or directory names, comma-separatedevery repoLimit it to these connected repos.
--give-up-afterduration: 2h, 30m, 1d or nevernoneHow long a vanished machine's work is waited for.
--disabledswitchoffRegister it taking no new steps, until enable. Added in 2.4

admin worker edit

Added in 2.4

kraft admin worker edit [flags] NAME

Changes a machine, or local: only the flags you give, and applies from the next step. With no flag it exits 2. local takes only --capacity and the groups.

FlagTypeDefaultMeaning
--capacityinteger or noneunchangedThe most sessions it may run at once. none drops the cap: the machine's own limit applies (for local, no limit).
--give-up-afterduration: 2h, 30m, 1d or neverunchangedAs for add. The machine learns the new value the next time it connects; the server uses it at once.
--groupgroup name, repeatableunchangedIts groups become exactly these.
--no-groupsswitchoffTake it out of every group. Not with --group.
--reposrepo IDs, names or directory names, comma-separatedunchangedLimit it to these connected repos.
--every-reposwitchoffLift the repo limit. Not with --repos. --repos all would name a repo called all, so this is a flag of its own.
--sshhost or ssh config aliasunchangedA new host for a machine Kraft dials.
RefusalCause
A refused --sshThe machine dials in, or a step runs on it, since a new host drops the connection.

admin worker enable

Added in 2.4

kraft admin worker enable [flags] NAME

Lets a machine, or local, take new steps again. It takes no flags.

admin worker disable

Added in 2.4

kraft admin worker disable [flags] NAME

Stops new steps starting on a machine, or on local; running steps finish, nothing new starts. It takes no flags. See Disabling a machine.

admin worker rotate-token

Added in 2.4

kraft admin worker rotate-token [flags] NAME

A new token for a dial-in machine, printed once with the serve command. The old one stops working at once. It takes no flags.

rotate-token ends the machine's connection; steps running on it wait for it, up to its give_up_after, until serve runs with the new token.

RefusalCause
Refused by the serverAn ssh machine and local have no token.

admin worker list

Added in 2.4

kraft admin worker list [flags]

Each machine: mode, online or offline and why, slots, groups, repos, last seen and Kraft version. It takes no flags.

Columns NAME MODE STATE SLOTS GROUPS REPOS LAST SEEN VERSION. STATE: online, offline: and why, or disabled. SLOTS: 1 of 2, (machine) for a lower own limit, 2 · no limit for local. --json prints the GET /api/workers answer.

A disabled machine that is also out of reach reads disabled · offline: and the reason.

admin worker remove

Added in 2.4

kraft admin worker remove [flags] NAME

Forgets the machine. Its token or ssh entry stops working and its connection ends. It takes no flags.

RefusalCause
Refused, naming the itemsA step runs on the machine: disable it and remove it once they end. A step held by an offline machine is freed by pausing or cancelling its item.
RefusedThe machine is local, which can't be removed.

admin worker serve

Added in 2.4

kraft admin worker serve [flags]

On a machine: connects to a server and stays connected. It takes no --json.

FlagTypeDefaultMeaning
--serverURLnoneDials that server and stays connected, redialling after a drop until you press Ctrl-C.
--tokentextnoneThe token worker add printed, for --server.
--stdioswitchoffSpeaks on standard input and output instead; the server runs it over ssh, and you don't run it by hand.

Exactly one of --server and --stdio is required. It prints one line per outcome to stderr: connected as NAME, refused: ..., disconnected: ... or cannot connect: ....

admin worker check

Added in 2.4

kraft admin worker check [flags]

On a machine: reports what it has for running steps, sandbox backends included.

FlagTypeDefaultMeaning
--serverURLnoneAlso tries a handshake with that server.
--tokentextnoneThe token for --server.

check prints one line per finding, as doctor does. It fails, and exits 1, when git is missing, when none of Kraft's agent CLIs is on PATH, or when --server is given and the handshake fails. A missing credential variable or sandbox runtime is a warning only, because an agent CLI can keep its login in a store this check can't see.

admin worker attach

Added in 2.4

kraft admin worker attach [flags]

Run by Kraft, not by hand: the local process of a step that runs on a machine, carrying its log and signals. --run-dir (the server's run directory), --item (the work item ID) and --session (the session ID) are all required. It takes no --json.

admin worker local

Added in 2.4

kraft admin worker local [flags]

Run by the server, not by hand: the local worker that starts every local session. --run-dir (the server's run directory) is required; --install names the install ID its socket is named for, the server's. It takes no --json. See The local worker.

Copyright © 2026