Hosts
The hosts rookery serve knows, their profiles, and what can be done to each.
| Operation | Kind | HTTP |
|---|---|---|
hosts.list | call | GET /v1/hosts |
hosts.get | call | GET /v1/hosts/{name} |
hosts.remove | call | DELETE /v1/hosts/{name} |
hosts.profile | call | GET /v1/hosts/{name}/profile |
hosts.save | call | PUT /v1/hosts/{name}/profile |
hosts.credentials | call | GET /v1/hosts/{name}/credentials |
hosts.actions | call | GET /v1/hosts/{name}/actions |
hosts.act | call | POST /v1/hosts/{name}/actions/{action} |
hosts.list
The saved hosts and whether each answers.
Needs the role view.
Result
HostInfo[]
{
"id": 1,
"op": "hosts.list"
}{
"id": 1,
"result": [
{
"address": "100.64.0.12",
"name": "status",
"power": {
"start": true,
"start_by": "text",
"state": "running",
"stop": true,
"stop_by": "text"
},
"reachable": true,
"type": "ssh"
}
]
}hosts.get
One host: its address, and whether it answers.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
Result
| Field | Type | Description |
|---|---|---|
address | string | Its SSH address. |
api (optional) | integer | null | |
applied (optional) | string | null | The rookery version its configuration was last applied with, when its rookeryd says, which it does for a host applied since. |
behind (optional) | Behind | null | |
error (optional) | string | null | Why it is not reachable. |
id (optional) | string | Its id, which stays when it is renamed; empty for a host that is not saved. |
machine (optional) | HostMachine | null | |
name | string | |
power | Power | Whether rookery can start and stop it, and whether it runs: running when its controller answers, else as its provisioner said last. |
reachable | boolean | |
rotating (optional) | boolean | A rotation of a key it logs in with is not done on it yet. |
seen (optional) | HostType | null | |
type | HostType | The type its profile means it to be. |
version (optional) | string | null | The version of its rookeryd. |
Errors
| Status | When |
|---|---|
| 404 | No such host |
{
"id": 1,
"op": "hosts.get",
"args": {
"name": "studio"
}
}{
"id": 1,
"result": {
"address": "100.64.0.12",
"name": "status",
"power": {
"start": true,
"start_by": "text",
"state": "running",
"stop": true,
"stop_by": "text"
},
"reachable": true,
"type": "ssh"
}
}hosts.remove
Remove a host's profile. The host itself is left as it is.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 404 | No such host |
| 409 | It has a machine rookery created, which is deleted first, or one is being created |
{
"id": 1,
"op": "hosts.remove",
"args": {
"name": "studio"
}
}{
"id": 1,
"result": {
"ok": true
}
}hosts.profile
A host's profile, as it is saved.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
Result
any
Errors
| Status | When |
|---|---|
| 404 | No such host |
{
"id": 1,
"op": "hosts.profile",
"args": {
"name": "studio"
}
}{
"id": 1,
"result": {
"columns": 2
}
}hosts.save
Save a host's profile: a new host, or a changed one. A host that is not a workstation needs only its type and access.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | The name to save it under: letters, digits, -, _ and ., and not in the shape of an id; or the id of a saved host |
Input
The whole profile. A workstation's has a builder object; a host of the type ssh or managed needs only type and access
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
Errors
| Status | When |
|---|---|
| 400 | Not a profile, or not a name |
{
"id": 1,
"op": "hosts.save",
"args": {
"name": "studio"
},
"data": {
"columns": 2
}
}{
"id": 1,
"result": {
"ok": true
}
}hosts.credentials
The passwords the server generated for a host's accounts.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
Result
| Field | Type | Description |
|---|---|---|
credentials | map of any | The password of each account, by the account's name. |
Errors
| Status | When |
|---|---|
| 404 | No such host |
{
"id": 1,
"op": "hosts.credentials",
"args": {
"name": "studio"
}
}{
"id": 1,
"result": {
"credentials": {}
}
}hosts.actions
What can be done to a host: the actions its controller lists, and rookery's own.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
Result
Action[]
Errors
| Status | When |
|---|---|
| 404 | No such host |
{
"id": 1,
"op": "hosts.actions",
"args": {
"name": "studio"
}
}{
"id": 1,
"result": [
{
"name": "status"
}
]
}hosts.act
Run one of a host's actions. One of rookery's that changes something is a job; an action of the host's controller is a session there, which a job follows unless it needs a terminal.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
name | path | yes | A saved host, by its name or its id (bare or as host_ID) |
action | path | yes | The action, as hosts.actions names it |
Input
Its arguments, and a token that makes asking again safe
Act | null
Result
| Field | Type | Description |
|---|---|---|
job (optional) | JobInfo | null | |
result (optional) | any | What an action that answers at once and changes nothing said. |
session (optional) | Session | null |
Errors
| Status | When |
|---|---|
| 400 | An argument is missing, or the body is not one |
| 403 | The caller's role is below the action's |
| 404 | No such host or action |
| 409 | Something else is being done to the host |
| 501 | It cannot run on this host now; the message says why |
| 502 | The host could not be reached |
{
"id": 1,
"op": "hosts.act",
"args": {
"name": "studio",
"action": "VALUE"
},
"data": {
"arguments": {},
"cols": 120,
"input_b64": "aGVsbG8K",
"rows": 40,
"sudo_password": "text",
"token": "text"
}
}{
"id": 1,
"result": {
"job": {
"id": "k3v9qz2m8w1x",
"started": "2026-11-12T09:30:00Z"
},
"result": null,
"session": {
"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"
}
}
}Types
The named types used on this page.
HostInfo
| Field | Type | Description |
|---|---|---|
address | string | Its SSH address. |
api (optional) | integer | null | |
applied (optional) | string | null | The rookery version its configuration was last applied with, when its rookeryd says, which it does for a host applied since. |
behind (optional) | Behind | null | |
error (optional) | string | null | Why it is not reachable. |
id (optional) | string | Its id, which stays when it is renamed; empty for a host that is not saved. |
machine (optional) | HostMachine | null | |
name | string | |
power | Power | Whether rookery can start and stop it, and whether it runs: running when its controller answers, else as its provisioner said last. |
reachable | boolean | |
rotating (optional) | boolean | A rotation of a key it logs in with is not done on it yet. |
seen (optional) | HostType | null | |
type | HostType | The type its profile means it to be. |
version (optional) | string | null | The version of its rookeryd. |
Behind
How a host's configuration differs from what rookery would apply now.
| Field | Type | Description |
|---|---|---|
changes | Change[] | rookery first when its version changed, then the plugins. |
HostMachine
The machine of a host, as rookery's record of the resource has it.
| Field | Type | Description |
|---|---|---|
external_id | string | The provisioner's id of it; empty until it is made. |
provisioner | string | The provisioner that made it, or is to make it. |
resource | string | rookery's id of the resource. |
state | string | As last seen, or planned for one not asked for yet. |
Power
How a host is started and stopped, and whether it runs. A host a
provisioner made is started and stopped through it, when its kind can;
any other declares in its profile's power how it is stopped.
| Field | Type | Description |
|---|---|---|
start | boolean | Whether rookery can start it. |
start_by (optional) | string | What starts it: provisioner, or empty when nothing does. |
state | PowerState | Whether it runs: what its controller or its provisioner said last. |
stop | boolean | Whether rookery can stop it. |
stop_by (optional) | string | What stops it: provisioner, controller, or empty when nothing does. |
HostType
What rookery does with a host: what its profile means it to be, or what it was seen to be. They are in the order of how much of rookery each has.
What rookery does with a host: what its profile means it to be, or what it was seen to be. They are in the order of how much of rookery each has.
Action
Something that can be done to a subject: a host, the installation, and later a provisioner or a resource. It says enough to build a form from.
| Field | Type | Description |
|---|---|---|
arguments (optional) | Argument[] | |
available (optional) | boolean | False, with why, when the subject's state rules it out now. |
changes (optional) | boolean | False when it only reads, and may be called at any time. |
collection (optional) | string | The id of the provisioner's collection it belongs to, whose items it makes, acts on or lists. The screens offer it there and not on the provisioner's page. |
confirm (optional) | string | null | The question to answer yes to before it runs. |
group (optional) | string | The group of the page it is listed in; Host when empty. |
help (optional) | string | |
label (optional) | string | |
name | string | |
role (optional) | Role | The least role that may run it. |
runs (optional) | Runs | Where an action runs. |
steps (optional) | ActionStep[] | What plugins add to it, in the order they run. |
terminal (optional) | boolean | It needs a terminal session attached; only a host runs these. |
why (optional) | string |
Act
What running an action is given.
| Field | Type | Description |
|---|---|---|
arguments (optional) | map of string | |
cols (optional) | integer | null | |
input_b64 (optional) | string | null | Bytes for the standard input of an action that takes them, in base64: the build context of a rookery for upgrade-server source=here. They go over HTTP when they are more than the portal carries. |
rows (optional) | integer | null | The size of the terminal, for an action that runs in one. |
sudo_password (optional) | string | null | The SSH user's sudo password, for an action that logs in to a host whose sudo asks for one. It is neither shown nor kept. |
token (optional) | string | null | Any text of the caller's. The same token again for the same subject and action answers with the job the first call started. |
JobInfo
A job of rookery: one run of an action, with its output kept where it ran.
| Field | Type | Description |
|---|---|---|
action (optional) | string | The action it runs, such as apply, rollout or provision. |
arguments (optional) | string[] | What it was started with, as people may see it: the command of a resource's exec, or an action's arguments as NAME=VALUE. Never a secret argument, a password or standard input. |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
host (optional) | string | The hosts it is about, for a reader: a name, or several with commas. |
host_id (optional) | string | The ids of those hosts, as host lists them; a host in a file by its path. |
id | string | |
report (optional) | RolloutReport | null | |
started | string | |
stopped_by (optional) | string | null | Who stopped it before it ended by itself. |
subject (optional) | string | What it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one. |
subject_name (optional) | string | What it was done to, by name as it is called now: host:NAME, provisioner:NAME, resource:ID or installation; by id for one that is gone. |
Session
| Field | Type | Description |
|---|---|---|
action (optional) | string | null | The action it was started for, if any. |
cols (optional) | integer | null | |
command | string[] | |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
id | string | |
kind | SessionKind | |
last_output (optional) | string | null | |
lost (optional) | boolean | It ended with rookeryd or the host, not by itself. |
output_size (optional) | integer | |
rows (optional) | integer | null | |
started | string | |
started_by | From | Who did something, as rookeryd saw it. |
steps (optional) | Step[] | |
title | string | |
user | string | |
viewers (optional) | integer |
Change
Something that changed since a host was applied: rookery itself or a plugin.
| Field | Type | Description |
|---|---|---|
from | string | The version the host was applied with. |
id | string | rookery, or a plugin's id. |
to | string | The version there is now; empty for a plugin that is gone, the same as from for one whose files changed. |
PowerState
Whether a host runs, as far as the server knows.
Whether a host runs, as far as the server knows.
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. |
Role
What a caller has to be allowed for an operation. Each role includes the ones before it.
What a caller has to be allowed for an operation. Each role includes the ones before it.
Runs
Where an action runs.
Where an action runs.
ActionStep
What a plugin adds to an action: a step run after it in the same run.
| Field | Type | Description |
|---|---|---|
help (optional) | string | |
label | string |
RolloutReport
The result of a roll-out, host by host in the order they were taken.
| Field | Type | Description |
|---|---|---|
hosts | RolloutHost[] | |
ok | boolean | Every host is done or current. |
SessionKind
From
Who did something, as rookeryd saw it.
| Field | Type | Description |
|---|---|---|
level | Level | |
session (optional) | string | null | |
uid | integer |
Step
| Field | Type | Description |
|---|---|---|
exit_code (optional) | integer | null | |
name | string | |
user | string |
RolloutHost
| Field | Type | Description |
|---|---|---|
changes (optional) | Change[] | What had changed, as it was before applying. |
error (optional) | string | What went wrong, for a failed host. |
name | string | |
rebooted (optional) | boolean | It was rebooted. |
state | RolloutState | How one host of a roll-out went. |
warnings (optional) | string[] | What did not go well without being a failure, such as an update step that ended badly. One stops the roll-out after this host. |
Level
RolloutState
How one host of a roll-out went.
How one host of a roll-out went.