Skip to Content

Hosts

The hosts rookery serve knows, their profiles, and what can be done to each.

OperationKindHTTP
hosts.listcallGET /v1/hosts
hosts.getcallGET /v1/hosts/{name}
hosts.removecallDELETE /v1/hosts/{name}
hosts.profilecallGET /v1/hosts/{name}/profile
hosts.savecallPUT /v1/hosts/{name}/profile
hosts.credentialscallGET /v1/hosts/{name}/credentials
hosts.actionscallGET /v1/hosts/{name}/actions
hosts.actcallPOST /v1/hosts/{name}/actions/{action}

hosts.list

The saved hosts and whether each answers.

Needs the role view.

Result

HostInfo[]

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

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)

Result

FieldTypeDescription
addressstringIts SSH address.
api (optional)integer | null
applied (optional)string | nullThe 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 | nullWhy it is not reachable.
id (optional)stringIts id, which stays when it is renamed; empty for a host that is not saved.
machine (optional)HostMachine | null
namestring
powerPowerWhether rookery can start and stop it, and whether it runs: running when its controller answers, else as its provisioner said last.
reachableboolean
rotating (optional)booleanA rotation of a key it logs in with is not done on it yet.
seen (optional)HostType | null
typeHostTypeThe type its profile means it to be.
version (optional)string | nullThe version of its rookeryd.

Errors

StatusWhen
404No such host
Request
{
  "id": 1,
  "op": "hosts.get",
  "args": {
    "name": "studio"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)

Result

FieldTypeDescription
okboolean

Errors

StatusWhen
404No such host
409It has a machine rookery created, which is deleted first, or one is being created
Request
{
  "id": 1,
  "op": "hosts.remove",
  "args": {
    "name": "studio"
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

hosts.profile

A host's profile, as it is saved.

Needs the role admin.

Arguments

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)

Result

any

Errors

StatusWhen
404No such host
Request
{
  "id": 1,
  "op": "hosts.profile",
  "args": {
    "name": "studio"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesThe 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

FieldTypeDescription
okboolean

Errors

StatusWhen
400Not a profile, or not a name
Request
{
  "id": 1,
  "op": "hosts.save",
  "args": {
    "name": "studio"
  },
  "data": {
    "columns": 2
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

hosts.credentials

The passwords the server generated for a host's accounts.

Needs the role admin.

Arguments

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)

Result

FieldTypeDescription
credentialsmap of anyThe password of each account, by the account's name.

Errors

StatusWhen
404No such host
Request
{
  "id": 1,
  "op": "hosts.credentials",
  "args": {
    "name": "studio"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)

Result

Action[]

Errors

StatusWhen
404No such host
Request
{
  "id": 1,
  "op": "hosts.actions",
  "args": {
    "name": "studio"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
namepathyesA saved host, by its name or its id (bare or as host_ID)
actionpathyesThe action, as hosts.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 the body is not one
403The caller's role is below the action's
404No such host or action
409Something else is being done to the host
501It cannot run on this host now; the message says why
502The host could not be reached
Request
{
  "id": 1,
  "op": "hosts.act",
  "args": {
    "name": "studio",
    "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"
    }
  }
}

Types

The named types used on this page.

HostInfo

FieldTypeDescription
addressstringIts SSH address.
api (optional)integer | null
applied (optional)string | nullThe 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 | nullWhy it is not reachable.
id (optional)stringIts id, which stays when it is renamed; empty for a host that is not saved.
machine (optional)HostMachine | null
namestring
powerPowerWhether rookery can start and stop it, and whether it runs: running when its controller answers, else as its provisioner said last.
reachableboolean
rotating (optional)booleanA rotation of a key it logs in with is not done on it yet.
seen (optional)HostType | null
typeHostTypeThe type its profile means it to be.
version (optional)string | nullThe version of its rookeryd.

Behind

How a host's configuration differs from what rookery would apply now.

FieldTypeDescription
changesChange[]rookery first when its version changed, then the plugins.

HostMachine

The machine of a host, as rookery's record of the resource has it.

FieldTypeDescription
external_idstringThe provisioner's id of it; empty until it is made.
provisionerstringThe provisioner that made it, or is to make it.
resourcestringrookery's id of the resource.
statestringAs 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.

FieldTypeDescription
startbooleanWhether rookery can start it.
start_by (optional)stringWhat starts it: provisioner, or empty when nothing does.
statePowerStateWhether it runs: what its controller or its provisioner said last.
stopbooleanWhether rookery can stop it.
stop_by (optional)stringWhat 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.

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.

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

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.

PowerState

Whether a host runs, as far as the server knows.

PowerState

Whether a host runs, as far as the server knows.

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

RolloutState

How one host of a roll-out went.

RolloutState

How one host of a roll-out went.

On this page