Actions
The host's actions and their arguments.
| Operation | Kind | HTTP |
|---|---|---|
actions.list | call | GET /v1/actions |
actions.run | call | POST /v1/actions/{action} |
actions.choices | call | GET /v1/actions/{action}/choices/{argument} |
actions.list
The actions the caller may run, in the order of the file.
Host and agent level. Through rookery serve it needs the role view.
Result
{
"id": 1,
"op": "actions.list"
}{
"id": 1,
"result": [
{
"name": "status"
}
]
}actions.run
Run an action. It and what extends it are the steps of one session.
Host and agent level. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
action | path | yes | An action's name, as the list gives it. |
wait | query | no | A duration such as 30s, at most 10m: answer when the command has ended, with what it wrote. |
Input
| Field | Type | Description |
|---|---|---|
arguments (optional) | map of string | |
cols (optional) | integer | null | |
input_b64 (optional) | string | null | |
rows (optional) | integer | null |
Result
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
{
"id": 1,
"op": "actions.run",
"args": {
"action": "VALUE",
"wait": "30s"
},
"data": {
"arguments": {},
"cols": 120,
"input_b64": "aGVsbG8K",
"rows": 40
}
}{
"id": 1,
"result": {
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent",
"output_b64": "aGVsbG8K",
"stderr_b64": "aGVsbG8K",
"stdout_b64": "aGVsbG8K",
"truncated": true
}
}actions.choices
The values to offer for an argument.
Host and agent level. Through rookery serve it needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
action | path | yes | An action's name, as the list gives it. |
argument | path | yes | The name of one of the action's arguments. |
Result
| Field | Type | Description |
|---|---|---|
choices | string[] |
{
"id": 1,
"op": "actions.choices",
"args": {
"action": "VALUE",
"argument": "snapshot"
}
}{
"id": 1,
"result": {
"choices": [
"text"
]
}
}Types
The named types used on this page.
HostAction
An action of the host's controller: an entry of /etc/rookery/actions.json.
Listed without run.
| Field | Type | Description |
|---|---|---|
agent (optional) | boolean | The agent may run it. |
arguments (optional) | Argument[] | |
confirm (optional) | string | null | |
extends (optional) | string[] | Actions it is a step of; it then has no row of its own. |
group (optional) | string | |
help (optional) | string | |
input (optional) | string | null | What the workstation sends on standard input: secrets. |
label (optional) | string | |
name | string | |
run (optional) | string | |
terminal (optional) | boolean | |
user (optional) | string |
Started
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
Argument
| Field | Type | Description |
|---|---|---|
choices (optional) | string | A command whose lines are the values to offer. |
confirm (optional) | string | For a yes or no: the question to answer yes to before the action runs with it on, instead of the action's own. |
default (optional) | string | |
fixed (optional) | string | Why it keeps its default here and cannot be given another value, such as destroying a machine no provisioner made. The screens show it greyed and say this instead of changing it. Empty when it can be changed. |
help (optional) | string | What it is for, in a sentence or two, beside its short label. |
kind (optional) | string | resource for an argument of a provisioner that sizes the machine: its CPUs, memory or disk. text for one whose value has several lines. boolean for a yes or no, which the screens show as a switch. Empty for any other argument. |
label (optional) | string | |
name | string | |
required (optional) | boolean | |
secret (optional) | boolean | What is given is a secret, such as a password: it is not shown as it is typed, nor kept, nor written to a job's output. |
values (optional) | string[] | The values a provisioner's argument takes, when it is a choice of a few. Empty for one that takes any text. |