Skip to Content

Actions

The host's actions and their arguments.

OperationKindHTTP
actions.listcallGET /v1/actions
actions.runcallPOST /v1/actions/{action}
actions.choicescallGET /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

HostAction[]

Request
{
  "id": 1,
  "op": "actions.list"
}
Reply
{
  "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

NameWhereRequiredDescription
actionpathyesAn action's name, as the list gives it.
waitquerynoA duration such as 30s, at most 10m: answer when the command has ended, with what it wrote.

Input

FieldTypeDescription
arguments (optional)map of string
cols (optional)integer | null
input_b64 (optional)string | null
rows (optional)integer | null

Result

Started

The answer to a start with wait=: the session and, when it has ended in time, what it wrote.

Request
{
  "id": 1,
  "op": "actions.run",
  "args": {
    "action": "VALUE",
    "wait": "30s"
  },
  "data": {
    "arguments": {},
    "cols": 120,
    "input_b64": "aGVsbG8K",
    "rows": 40
  }
}
Reply
{
  "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

NameWhereRequiredDescription
actionpathyesAn action's name, as the list gives it.
argumentpathyesThe name of one of the action's arguments.

Result

FieldTypeDescription
choicesstring[]
Request
{
  "id": 1,
  "op": "actions.choices",
  "args": {
    "action": "VALUE",
    "argument": "snapshot"
  }
}
Reply
{
  "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.

FieldTypeDescription
agent (optional)booleanThe 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 | nullWhat the workstation sends on standard input: secrets.
label (optional)string
namestring
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.

Started

The answer to a start with wait=: the session and, when it has ended in time, what it wrote.

Argument

FieldTypeDescription
choices (optional)stringA command whose lines are the values to offer.
confirm (optional)stringFor 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)stringWhy 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)stringWhat it is for, in a sentence or two, beside its short label.
kind (optional)stringresource 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
namestring
required (optional)boolean
secret (optional)booleanWhat 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.

On this page