Nodes
Nodes are the machines that run agents. Read their status, health and metrics, set which projects they serve, manage their GitHub Actions runner pools, and configure cloud node defaults and hosts.
List cloud node defaults
Lists the cloud node launch settings filed for the AWS credentials the caller may view, newest first, each with its credential's name. Requires the Org Owner or Org Admin role.
Create cloud node defaults
Files the launch settings (region, machine image, subnet, security group and optional shared storage) for one AWS credential, which cannot create cloud nodes until it has them. Requires the Org Owner or Org Admin role. Returns 409 if the credential already has defaults.
Delete cloud node defaults
Removes a cloud node defaults entry; nodes already launched with it keep running, but its credential cannot launch new cloud nodes. Requires the Org Owner or Org Admin role. Returns 204 with no body.
Update cloud node defaults
Changes the fields sent on a cloud node defaults entry; required fields cannot be set to null. Affects only nodes launched afterwards. Requires the Org Owner or Org Admin role.
Get cloud node options
Returns the allowed instance types and the AWS credentials the caller may view, each marked with whether it has launch defaults and their region. An empty instance type list means cloud node creation is off. Requires the Org Owner or Org Admin role.
Send a command to a node
Runs a command, such as a worktree, stack or agent account operation, on a node the caller may change, and waits for its reply. Worktree and stack commands need worktree edit permission and the rest system create permission; commands reserved to Jaah return 403. Returns 201 with the command's status and result, 503 when the node is not connected, and 504 when it does not answer in time.
List hosts
Lists the machines the caller may see as hosts, each with its state, origin and the nodes it carries, one page at a time (pass `next_cursor` back as `cursor`). Your nodes on shared machines are grouped under one entry that names no machine. Requires `nodes:view`.
Rename host
Renames a host: the name shown and its machine's own name change together. Returns 422 with a sentence saying why when the name cannot be used. Requires the Org Owner or Org Admin role.
List nodes
Lists the nodes the caller may see, with status, last contact, worktree, runner and agent account counts, and latest resource readings. Organization-wide node view access shows every node; otherwise only nodes hosting a worktree or environment of a project the caller can reach appear.
List intents
Returns one page of queued worktree actions sent to the nodes the caller may see, pending by default or retired with `set=retired`, plus queue counts. Filter by `node`, `verb`, `outcome`, `state` or `refusing`; page with `page` and `per`.
Delete node
Deregisters a node, ends the work in its worktrees, erases them and terminates the machine if Jaah launched it. Requires the Org Owner or Org Admin role. Returns which erasures failed and whether the machine was terminated.
Get node
Returns one node's full record by name, including status, platform, counts and configuration. Returns 404 for a node the caller cannot see.
Update node
Changes the fields sent on a node's record, such as name, description, tags, `enabled` and `draining`; a node cannot be both draining and disabled (422). Shared-account and host settings require the Org Owner or Org Admin role. Returns the updated node, or 404 for a node the caller cannot see.
Delete GitHub Actions runner pool
Asks the node to deregister and remove its GitHub Actions runners; the pool is deleted once the node reports it is clear. With `force=true`, deletes the pool at once and leaves any registered runners unmanaged. Returns the pool.
Get GitHub Actions runner pool
Returns the node's GitHub Actions runner pool, with its project, desired count, state and any runners registered beyond that count, or `pool: null` when the node has none.
Set GitHub Actions runner pool
Creates or replaces the node's GitHub Actions runner pool from a project, credential, runner count and state, then tells the node to apply it. A pool with installed runners cannot move to another project or credential (422); a new project or credential is checked for runner registration rights, and added runners count against the organization's runner limit. Returns the pool.
Get node health
Returns the node's health verdicts, reporting clocks with their staleness bounds, and configuration drift. Read-only; returns 404 for a node the caller cannot see.
Get node metrics
Returns the node's CPU, memory, disk and network series over the last `hours` (default 6), plus its newest reading. A node that has never reported returns an empty series.
Get node projects
Lists the projects the node runs, with each one's worktree count and whether a node group placed it, plus the organization's other projects it could run.
Set node projects
Replaces the projects the node runs, with an optional fixed worktree count per project, then creates or removes worktrees to match; a project a node group placed stays assigned when omitted. Requires the Org Owner or Org Admin role. Returns the new assignments plus the worktrees created and removed, tasks requeued and any warnings.
List host machines
Lists the hosts the caller may see, with each host's status, hosting type and the nodes it carries. Requires the Org Owner or Org Admin role.
Delete host
Deletes a host and terminates its machine if Jaah launched it. Returns 409 while the host still carries any node. Requires the Org Owner or Org Admin role.
Update host
Offers one of the operator's own hosts for Shared hosting, up to `shared_capacity` nodes (1 to 99), or stops offering it with `null`. Returns 422 for any other host. Requires an operator.
List virtual nodes
Lists the nodes on one host with each node's organization, slot, state, failure reason, last contact, and disk and inode use against its caps. Requires the Org Owner or Org Admin role.
Create virtual node
Creates a node on a host for the caller's own organization, named by `org_id` (any other organization returns 422), and tells the host to set it up. Requires the Org Owner or Org Admin role. Returns 201 with the new node's ids.
Delete virtual node
Deletes one node from a host with the same teardown as deleting any node, and tells the host to remove it. Returns 409 if it is already being torn down. Requires the Org Owner or Org Admin role.