Skip to Content

Resources

What provisioners made for rookery, a host's machine among them: creating, changing, removing, their actions, logs and endpoints.

OperationKindHTTP
resources.listcallGET /v1/resources
resources.createcallPOST /v1/resources
resources.getcallGET /v1/resources/{id}
resources.changecallPUT /v1/resources/{id}
resources.removecallDELETE /v1/resources/{id}
resources.actionscallGET /v1/resources/{id}/actions
resources.actcallPOST /v1/resources/{id}/actions/{action}
resources.logscallGET /v1/resources/{id}/logs
resources.followstreamGET /v1/resources/{id}/logs
resources.connectstreamGET /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

NameWhereRequiredDescription
provisionerquerynoOnly those of this provisioner, by its name.
kindquerynoOnly those of this kind, such as machine or deployment.
hostquerynoOnly the machine of this saved host.

Result

Resource[]

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

FieldTypeDescription
arguments (optional)map of stringValues of the provisioner's and the kind's arguments; the others take their settings or defaults.
host (optional)string | nullThe saved host a machine is made for, and set up as.
kind (optional)stringmachine when empty.
name (optional)stringThe host's name for a host's machine when empty.
provisionerstringThe provisioner, by name or id.
secrets (optional)ResourceSecret[]
spec (optional)string | nullThe specification, for a kind that has one, as its plugin reads it.
token (optional)string | nullAny text of the caller's. The same token again answers with the resource and the job the first call started.

Errors

StatusWhen
400An argument, a secret or the specification is missing or does not fit; the message says which
404No such host or provisioner
409One of that name exists already, or something else is being done to it
Request
{
  "id": 1,
  "op": "resources.create",
  "data": {
    "arguments": {},
    "host": "studio",
    "kind": "process",
    "name": "status",
    "provisioner": "text",
    "secrets": [
      {
        "env": "text",
        "name": "status"
      }
    ],
    "spec": "text",
    "token": "text"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID

Result

FieldTypeDescription
address (optional)string
arguments (optional)map of string
checked (optional)stringWhen its provisioner was last asked about it.
created (optional)stringWhen 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)stringThe provisioner's id of it; empty until create said it.
host (optional)string | nullThe host a machine belongs to, if any, by name; a profile in a file by its path.
host_id (optional)stringThe id of that host, when it is a saved host.
idstringrookery's id of it, stable for the life of the record.
kindstringmachine, or a kind the plugin declares.
namestringUnique per provisioner and kind.
problem (optional)stringWhy its state is unknown, or what is wrong with it.
provisionerstringThe name of the provisioner that made it.
provisioner_id (optional)stringThe 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)stringThe SHA-256 of its stored specification, for a kind that has one.
statestringcreating, 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

StatusWhen
404No such resource
Request
{
  "id": 1,
  "op": "resources.get",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID

Input

What changes, and a token that makes asking again safe

FieldTypeDescription
arguments (optional)map of stringValues of the kind's arguments, over those it has.
secrets (optional)ResourceSecret[] | null
spec (optional)string | null
token (optional)string | null

Errors

StatusWhen
400An argument, a secret or the specification does not fit
404No such resource
409Something else is being done to it
501Its kind cannot be changed, or it is not made yet
Request
{
  "id": 1,
  "op": "resources.change",
  "args": {
    "id": "k3v9qz2m8w1x"
  },
  "data": {
    "arguments": {},
    "secrets": [
      {
        "env": "text",
        "name": "status"
      }
    ],
    "spec": "text",
    "token": "text"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID
tokenquerynoAny text of the caller's; the same again answers with the first job.

Errors

StatusWhen
404No such resource
409Something else is being done to it
501Its provisioner cannot be asked now; the message says why
Request
{
  "id": 1,
  "op": "resources.remove",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID

Result

Action[]

Errors

StatusWhen
404No such resource
Request
{
  "id": 1,
  "op": "resources.actions",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID
actionpathyesThe action, as resources.actions names it

Input

Its arguments, and a token that makes asking again safe

Act | null

Result

FieldTypeDescription
job (optional)JobInfo | null
result (optional)anyWhat an action that answers at once and changes nothing said.
session (optional)Session | null

Errors

StatusWhen
400An argument is missing or unknown, or the body is not one
403The caller's role is below the action's
404No such resource or action
409Something else is being done to it
501It cannot run now; the message says why
502The provisioner failed
Request
{
  "id": 1,
  "op": "resources.act",
  "args": {
    "id": "k3v9qz2m8w1x",
    "action": "VALUE"
  },
  "data": {
    "arguments": {},
    "cols": 120,
    "input_b64": "aGVsbG8K",
    "rows": 40,
    "sudo_password": "text",
    "token": "text"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesrookery's id of the resource, bare or as res_ID
tailquerynoThe 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

StatusWhen
400Its kind gives no logs, or it is not made yet
404No such resource
Request
{
  "id": 1,
  "op": "resources.logs",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyes
tailquerynoThe last so many lines first; all when 0 (default 100).

Frames from the server

FrameKindDescription
outputbinaryLines of its log.
exitedJSONThe log ended, or the provisioner stopped giving it. The last frame; with error when it failed. Example: {"exited":{"exit_code":0}}
Request
{
  "id": 1,
  "op": "resources.follow",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "exited": {
      "exit_code": 0
    }
  }
}

// binary: 00 00 00 01, then the bytes

End 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

NameWhereRequiredDescription
idpathyes
endpointpathyes

Frames from the server

FrameKindDescription
bytesbinaryWhat the endpoint sent.
eofJSONThe 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

FrameKindDescription
bytesbinaryBytes for the endpoint.
eofJSONThe client sends no more, and the endpoint reads the end. What it sends still comes back. Example: {"eof":true}
Request
{
  "id": 1,
  "op": "resources.connect",
  "args": {
    "id": "k3v9qz2m8w1x",
    "endpoint": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "eof": true
  }
}

// binary: 00 00 00 01, then the bytes

End 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.

FieldTypeDescription
address (optional)string
arguments (optional)map of string
checked (optional)stringWhen its provisioner was last asked about it.
created (optional)stringWhen 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)stringThe provisioner's id of it; empty until create said it.
host (optional)string | nullThe host a machine belongs to, if any, by name; a profile in a file by its path.
host_id (optional)stringThe id of that host, when it is a saved host.
idstringrookery's id of it, stable for the life of the record.
kindstringmachine, or a kind the plugin declares.
namestringUnique per provisioner and kind.
problem (optional)stringWhy its state is unknown, or what is wrong with it.
provisionerstringThe name of the provisioner that made it.
provisioner_id (optional)stringThe 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)stringThe SHA-256 of its stored specification, for a kind that has one.
statestringcreating, 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.

FieldTypeDescription
env (optional)stringThe environment variable it becomes; the secret's name when empty.
namestringThe 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.

FieldTypeDescription
addressstringAn IP address or a DNS name.
hint (optional)stringWhat speaks there, for people, such as http or postgres.
local (optional)booleanThe engine runs on the server's own machine, so the address is one the server reaches as it is, a loopback address among them.
namestringUnique among the resource's endpoints: lowercase letters, digits, -, _ and ..
portinteger
protocolstringtcp 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.

FieldTypeDescription
arguments (optional)Argument[]
available (optional)booleanFalse, with why, when the subject's state rules it out now.
changes (optional)booleanFalse when it only reads, and may be called at any time.
collection (optional)stringThe 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 | nullThe question to answer yes to before it runs.
group (optional)stringThe group of the page it is listed in; Host when empty.
help (optional)string
label (optional)string
namestring
role (optional)RoleThe least role that may run it.
runs (optional)RunsWhere an action runs.
steps (optional)ActionStep[]What plugins add to it, in the order they run.
terminal (optional)booleanIt needs a terminal session attached; only a host runs these.
why (optional)string

Act

What running an action is given.

FieldTypeDescription
arguments (optional)map of string
cols (optional)integer | null
input_b64 (optional)string | nullBytes 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 | nullThe size of the terminal, for an action that runs in one.
sudo_password (optional)string | nullThe 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 | nullAny 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.

FieldTypeDescription
action (optional)stringThe 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)stringThe hosts it is about, for a reader: a name, or several with commas.
host_id (optional)stringThe ids of those hosts, as host lists them; a host in a file by its path.
idstring
report (optional)RolloutReport | null
startedstring
stopped_by (optional)string | nullWho stopped it before it ended by itself.
subject (optional)stringWhat it was done to, by id: host:ID, provisioner:ID, resource:ID or installation. Empty for a job recorded without one.
subject_name (optional)stringWhat 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

FieldTypeDescription
action (optional)string | nullThe action it was started for, if any.
cols (optional)integer | null
commandstring[]
ended (optional)string | null
exit_code (optional)integer | null
idstring
kindSessionKind
last_output (optional)string | null
lost (optional)booleanIt ended with rookeryd or the host, not by itself.
output_size (optional)integer
rows (optional)integer | null
startedstring
started_byFromWho did something, as rookeryd saw it.
steps (optional)Step[]
titlestring
userstring
viewers (optional)integer

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.

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Role

What a caller has to be allowed for an operation. Each role includes the ones before it.

Runs

Where an action runs.

Runs

Where an action runs.

ActionStep

What a plugin adds to an action: a step run after it in the same run.

FieldTypeDescription
help (optional)string
labelstring

RolloutReport

The result of a roll-out, host by host in the order they were taken.

FieldTypeDescription
hostsRolloutHost[]
okbooleanEvery host is done or current.

SessionKind

SessionKind

From

Who did something, as rookeryd saw it.

FieldTypeDescription
levelLevel
session (optional)string | null
uidinteger

Step

FieldTypeDescription
exit_code (optional)integer | null
namestring
userstring

RolloutHost

FieldTypeDescription
changes (optional)Change[]What had changed, as it was before applying.
error (optional)stringWhat went wrong, for a failed host.
namestring
rebooted (optional)booleanIt was rebooted.
stateRolloutStateHow 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

Level

Change

Something that changed since a host was applied: rookery itself or a plugin.

FieldTypeDescription
fromstringThe version the host was applied with.
idstringrookery, or a plugin's id.
tostringThe 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.

RolloutState

How one host of a roll-out went.

On this page