Resources
What provisioners made for rookery, a host's machine among them: creating, changing, removing, their actions, logs and endpoints.
| Operation | Kind | HTTP |
|---|---|---|
resources.list | call | GET /v1/resources |
resources.create | call | POST /v1/resources |
resources.get | call | GET /v1/resources/{id} |
resources.change | call | PUT /v1/resources/{id} |
resources.remove | call | DELETE /v1/resources/{id} |
resources.actions | call | GET /v1/resources/{id}/actions |
resources.act | call | POST /v1/resources/{id}/actions/{action} |
resources.logs | call | GET /v1/resources/{id}/logs |
resources.follow | stream | GET /v1/resources/{id}/logs |
resources.connect | stream | GET /v1/resources/{id}/endpoints/{endpoint} |
resources.list
What provisioners made for rookery, as rookery's records have it. Nothing is asked of the provisioners.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
provisioner | query | no | Only those of this provisioner, by its name. |
kind | query | no | Only those of this kind, such as machine or deployment. |
host | query | no | Only the machine of this saved host. |
Result
Resource[]
{
"id": 1,
"op": "resources.list"
}{
"id": 1,
"result": [
{
"id": "k3v9qz2m8w1x",
"kind": "process",
"name": "status",
"provisioner": "text",
"state": "text"
}
]
}resources.create
Create a resource with a provisioner, as a job: a host's machine, which is then set up as the host, or a kind its plugin declares, such as a deployment from a specification.
Needs the role admin.
Input
The provisioner, the kind, its name or host, arguments, the specification and the secrets it is given, and a token that makes asking again safe
| Field | Type | Description |
|---|---|---|
arguments (optional) | map of string | Values of the provisioner's and the kind's arguments; the others take their settings or defaults. |
host (optional) | string | null | The saved host a machine is made for, and set up as. |
kind (optional) | string | machine when empty. |
name (optional) | string | The host's name for a host's machine when empty. |
provisioner | string | The provisioner, by name or id. |
secrets (optional) | ResourceSecret[] | |
spec (optional) | string | null | The specification, for a kind that has one, as its plugin reads it. |
token (optional) | string | null | Any text of the caller's. The same token again answers with the resource and the job the first call started. |
Errors
| Status | When |
|---|---|
| 400 | An argument, a secret or the specification is missing or does not fit; the message says which |
| 404 | No such host or provisioner |
| 409 | One of that name exists already, or something else is being done to it |
{
"id": 1,
"op": "resources.create",
"data": {
"arguments": {},
"host": "studio",
"kind": "process",
"name": "status",
"provisioner": "text",
"secrets": [
{
"env": "text",
"name": "status"
}
],
"spec": "text",
"token": "text"
}
}{
"id": 1,
"result": null
}resources.get
One resource, as its provisioner says it is now. One it no longer finds is missing, and its record stays.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
Result
| Field | Type | Description |
|---|---|---|
address (optional) | string | |
arguments (optional) | map of string | |
checked (optional) | string | When its provisioner was last asked about it. |
created (optional) | string | When it was asked for, RFC 3339. |
endpoints (optional) | Endpoint[] | Where it can be reached, as its provisioner last said: when it was made, changed or checked. |
external_id (optional) | string | The provisioner's id of it; empty until create said it. |
host (optional) | string | null | The host a machine belongs to, if any, by name; a profile in a file by its path. |
host_id (optional) | string | The id of that host, when it is a saved host. |
id | string | rookery's id of it, stable for the life of the record. |
kind | string | machine, or a kind the plugin declares. |
name | string | Unique per provisioner and kind. |
problem (optional) | string | Why its state is unknown, or what is wrong with it. |
provisioner | string | The name of the provisioner that made it. |
provisioner_id (optional) | string | The id of that provisioner, when it is registered. |
secrets (optional) | ResourceSecret[] | The rookery secrets it is given, by name; never their values. |
spec_sha256 (optional) | string | The SHA-256 of its stored specification, for a kind that has one. |
state | string | creating, running, stopped, missing or unknown, as last seen; planned for a host's machine saved to be made later, as a duplicate's is. |
verbs (optional) | string[] | What can be done to it besides being removed: start, stop, change, logs, exec, as its kind declares. |
Errors
| Status | When |
|---|---|
| 404 | No such resource |
{
"id": 1,
"op": "resources.get",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"id": "k3v9qz2m8w1x",
"kind": "process",
"name": "status",
"provisioner": "text",
"state": "text"
}
}resources.change
Change a resource, as a job: other values of its kind's arguments, a new specification, other secrets. What is not given stays.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
Input
What changes, and a token that makes asking again safe
| Field | Type | Description |
|---|---|---|
arguments (optional) | map of string | Values of the kind's arguments, over those it has. |
secrets (optional) | ResourceSecret[] | null | |
spec (optional) | string | null | |
token (optional) | string | null |
Errors
| Status | When |
|---|---|
| 400 | An argument, a secret or the specification does not fit |
| 404 | No such resource |
| 409 | Something else is being done to it |
| 501 | Its kind cannot be changed, or it is not made yet |
{
"id": 1,
"op": "resources.change",
"args": {
"id": "k3v9qz2m8w1x"
},
"data": {
"arguments": {},
"secrets": [
{
"env": "text",
"name": "status"
}
],
"spec": "text",
"token": "text"
}
}{
"id": 1,
"result": null
}resources.remove
Remove a resource with its provisioner, as a job, and forget it. A host's profile stays.
Needs the role admin.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
token | query | no | Any text of the caller's; the same again answers with the first job. |
Errors
| Status | When |
|---|---|
| 404 | No such resource |
| 409 | Something else is being done to it |
| 501 | Its provisioner cannot be asked now; the message says why |
{
"id": 1,
"op": "resources.remove",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": null
}resources.actions
What can be done to a resource: start, stop and change as its kind can, its plugin's actions of the kind, and removing it.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
Result
Action[]
Errors
| Status | When |
|---|---|
| 404 | No such resource |
{
"id": 1,
"op": "resources.actions",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": [
{
"name": "status"
}
]
}resources.act
Run one of a resource's actions. One that changes something is a job of the resource, which holds its lock; one that only reads answers at once.
Needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
action | path | yes | The action, as resources.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 unknown, or the body is not one |
| 403 | The caller's role is below the action's |
| 404 | No such resource or action |
| 409 | Something else is being done to it |
| 501 | It cannot run now; the message says why |
| 502 | The provisioner failed |
{
"id": 1,
"op": "resources.act",
"args": {
"id": "k3v9qz2m8w1x",
"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"
}
}
}resources.logs
What a resource wrote, as its provisioner gives it, with secrets masked: the last lines as text, or as a WebSocket those and what follows.
Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | rookery's id of the resource, bare or as res_ID |
tail | query | no | The last so many lines; all when 0 (default 100). |
Result
Bytes: {"base64": …, "content_type": …} on the portal, the response body over HTTP (text/plain).
Errors
| Status | When |
|---|---|
| 400 | Its kind gives no logs, or it is not made yet |
| 404 | No such resource |
{
"id": 1,
"op": "resources.logs",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"base64": "aGVsbG8K",
"content_type": "text/plain"
}
}resources.follow
What a resource writes, as its provisioner gives it, with secrets masked: the last lines, then what follows.
A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | |
tail | query | no | The last so many lines first; all when 0 (default 100). |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
output | binary | Lines of its log. |
exited | JSON | The log ended, or the provisioner stopped giving it. The last frame; with error when it failed. Example: {"exited":{"exit_code":0}} |
{
"id": 1,
"op": "resources.follow",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"exited": {
"exit_code": 0
}
}
}
// binary: 00 00 00 01, then the bytesEnd the subscription with {"sub": 1, "end": true}.
resources.connect
A TCP connection to an endpoint its provisioner reported for a resource, named by the endpoint's name or its port. The server dials it first, so one that nothing answers on, or an address rookery refuses, is an error and not a stream.
A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | |
endpoint | path | yes |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
bytes | binary | What the endpoint sent. |
eof | JSON | The endpoint closed its side. Bytes sent towards it still arrive. The stream ends once both sides have sent this. Example: {"eof":true} |
Frames to the server
| Frame | Kind | Description |
|---|---|---|
bytes | binary | Bytes for the endpoint. |
eof | JSON | The client sends no more, and the endpoint reads the end. What it sends still comes back. Example: {"eof":true} |
{
"id": 1,
"op": "resources.connect",
"args": {
"id": "k3v9qz2m8w1x",
"endpoint": "VALUE"
}
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"eof": true
}
}
// binary: 00 00 00 01, then the bytesEnd the subscription with {"sub": 1, "end": true}.
Types
The named types used on this page.
Resource
Something a provisioner made for rookery: a machine, which may be a host's, or a kind its plugin names, such as a deployment.
| Field | Type | Description |
|---|---|---|
address (optional) | string | |
arguments (optional) | map of string | |
checked (optional) | string | When its provisioner was last asked about it. |
created (optional) | string | When it was asked for, RFC 3339. |
endpoints (optional) | Endpoint[] | Where it can be reached, as its provisioner last said: when it was made, changed or checked. |
external_id (optional) | string | The provisioner's id of it; empty until create said it. |
host (optional) | string | null | The host a machine belongs to, if any, by name; a profile in a file by its path. |
host_id (optional) | string | The id of that host, when it is a saved host. |
id | string | rookery's id of it, stable for the life of the record. |
kind | string | machine, or a kind the plugin declares. |
name | string | Unique per provisioner and kind. |
problem (optional) | string | Why its state is unknown, or what is wrong with it. |
provisioner | string | The name of the provisioner that made it. |
provisioner_id (optional) | string | The id of that provisioner, when it is registered. |
secrets (optional) | ResourceSecret[] | The rookery secrets it is given, by name; never their values. |
spec_sha256 (optional) | string | The SHA-256 of its stored specification, for a kind that has one. |
state | string | creating, running, stopped, missing or unknown, as last seen; planned for a host's machine saved to be made later, as a duplicate's is. |
verbs (optional) | string[] | What can be done to it besides being removed: start, stop, change, logs, exec, as its kind declares. |
ResourceSecret
A rookery secret a resource is given in its environment, by name. Its value is resolved when the provisioner is called and never kept with the resource.
| Field | Type | Description |
|---|---|---|
env (optional) | string | The environment variable it becomes; the secret's name when empty. |
name | string | The name of the rookery secret. |
Endpoint
Where a resource can be reached: an address and a port, as its provisioner reports it. The address is as seen from the machine the provisioner's engine runs on, such as a Docker engine or an Incus server.
| Field | Type | Description |
|---|---|---|
address | string | An IP address or a DNS name. |
hint (optional) | string | What speaks there, for people, such as http or postgres. |
local (optional) | boolean | The engine runs on the server's own machine, so the address is one the server reaches as it is, a loopback address among them. |
name | string | Unique among the resource's endpoints: lowercase letters, digits, -, _ and .. |
port | integer | |
protocol | string | tcp or udp. |
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 |
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
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. |
RolloutState
How one host of a roll-out went.
How one host of a roll-out went.