Machine verbs
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
| Verb | What it does |
|---|---|
admin worker add | Registers a machine; a dial-in one gets a token. Added in 2.4 |
admin worker edit | Changes a machine; the rest stays. Added in 2.4 |
admin worker enable | Lets a machine take new steps again. Added in 2.4 |
admin worker disable | Takes no new steps on a machine; running ones finish. Added in 2.4 |
admin worker rotate-token | A new token for a dial-in machine. Added in 2.4 |
admin worker list | The machines, online or offline and why. Added in 2.4 |
admin worker remove | Forgets a machine and ends its connection. Added in 2.4 |
admin worker serve | On a machine: connects to a server. Added in 2.4 |
admin worker check | On a machine: what it has for running steps. Added in 2.4 |
admin worker attach | Run by Kraft: a remote step's local process. Added in 2.4 |
admin worker local | Run 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.
| Refusal | Cause |
|---|---|
403 | A 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--ssh | host or ssh config alias | none: the machine dials in | A host or ssh config alias for the server to dial. |
--capacity | integer | the machine's own limit, else 1 | The most sessions it may run at once. The lower of this and the machine's own limit applies. |
--group | group name, repeatable | none | Put it in group G, which a step's runner: can name. See Groups. Added in 2.4 |
--repos | repo IDs, names or directory names, comma-separated | every repo | Limit it to these connected repos. |
--give-up-after | duration: 2h, 30m, 1d or never | none | How long a vanished machine's work is waited for. |
--disabled | switch | off | Register 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--capacity | integer or none | unchanged | The most sessions it may run at once. none drops the cap: the machine's own limit applies (for local, no limit). |
--give-up-after | duration: 2h, 30m, 1d or never | unchanged | As for add. The machine learns the new value the next time it connects; the server uses it at once. |
--group | group name, repeatable | unchanged | Its groups become exactly these. |
--no-groups | switch | off | Take it out of every group. Not with --group. |
--repos | repo IDs, names or directory names, comma-separated | unchanged | Limit it to these connected repos. |
--every-repo | switch | off | Lift the repo limit. Not with --repos. --repos all would name a repo called all, so this is a flag of its own. |
--ssh | host or ssh config alias | unchanged | A new host for a machine Kraft dials. |
| Refusal | Cause |
|---|---|
A refused --ssh | The 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.
| Refusal | Cause |
|---|---|
| Refused by the server | An 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.
| Refusal | Cause |
|---|---|
| Refused, naming the items | A 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. |
| Refused | The 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--server | URL | none | Dials that server and stays connected, redialling after a drop until you press Ctrl-C. |
--token | text | none | The token worker add printed, for --server. |
--stdio | switch | off | Speaks 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.
| Flag | Type | Default | Meaning |
|---|---|---|---|
--server | URL | none | Also tries a handshake with that server. |
--token | text | none | The 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.