Nodes
Nodes are the machines that run agents. Read their status, health and metrics, group them into node groups that projects run on, manage their GitHub Actions runner pools, configure cloud connections, hosts and virtual nodes, choose a node's NodeLinks, and send commands to nodes and read the command log.
List cloud connections
Lists the cloud connections over the AWS credentials the caller may view, newest first, each with its credential's name. A connection is the credential, region, image and network a cloud node launches from. Requires the Org Owner or Org Admin role.
Create cloud connection
Creates a cloud connection over one credential of the chosen `provider` (`aws` when omitted) in one region; a cloud not on the org's plan returns 403. A blank `image` (or `ami_id`) takes the newest Ubuntu LTS image at every launch, and blank `network` fields are resolved now and returned resolved (on AWS the default VPC and a `jaah-node` group). Requires the Org Owner or Org Admin role, and returns 502 with the cloud's own message when it refuses the lookup.
Look up regions
Lists the AWS regions a cloud connection may name, as code and display name, without using any credential. Requires the Org Owner or Org Admin role.
Look up security groups
Lists the security groups an AWS credential can see in a region, for the cloud connection form. Requires the Org Owner or Org Admin role and a credential the caller may view; returns 502 with AWS's own message when AWS refuses.
Look up subnets
Lists the subnets an AWS credential can see in a region, for the cloud connection form. Requires the Org Owner or Org Admin role and a credential the caller may view; returns 502 with AWS's own message when AWS refuses.
Look up connection field
Lists the choices one field of a cloud connection form offers (`region`, or a network field such as `subnet_id`), signed with a credential the caller may view. A cloud not on the org's plan returns 403. Requires the Org Owner or Org Admin role; returns 502 with the cloud's own message when it refuses.
Get cloud connection options
Returns the allowed instance types, the AWS credentials the caller may view (each with the region its credential names, if any) and the cloud connections to pick from. An empty instance type list means cloud node creation is off. Requires the Org Owner or Org Admin role.
List cloud providers
Lists the clouds the caller's org may connect (only those its plan switches on), each with its label, what it calls an account, the credential type that signs for it and its connection form's fields. Requires the Org Owner or Org Admin role.
Delete cloud connection
Removes a cloud connection; nodes already launched from it keep running, and a node group still using it makes this a 409. Requires the Org Owner or Org Admin role. Returns 204 with no body.
Update cloud connection
Changes the fields sent on a cloud connection; required fields cannot be set to null, and a changed region or credential, or a blank subnet or security group, resolves the network again. Affects only nodes launched afterwards. Requires the Org Owner or Org Admin role.
Get command log
Lists commands sent to nodes, newest first, one page at a time, with a `total` of matching rows. Filters by node, status, text search and time range; shows commands for nodes the caller can see and those bound to no node. Requires permission to view system settings.
Get command log entry
Returns one command sent to a node: its type, status, node, who sent it, when, and its arguments and result. A command the caller could not list is a 404. Requires permission to view system settings.
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 or system create permission, and the rest system create permission, except that a member who may add agent accounts may run the add-account steps for their own account; 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, by name unless `sort` says otherwise. 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.
Restart host
Restarts a host now: `target: nodes` restarts the Jaah service of each of your organization's nodes on it, and `target: host` reboots a cloud machine or restarts every Jaah service on a self-hosted one. A host restart returns 409 while another organization's node runs on the host. 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 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`.
Download macOS Full Disk Access profile
Downloads the `.mobileconfig` profile an MDM installs on a Mac node to grant `/Library/Jaah/bin/jaah-anchor` Full Disk Access, which NodeLinks need. Returns 404 while the environment has no Apple Team ID configured. Requires the Org Owner or Org Admin role.
List nodes page
Returns one page of the nodes the caller may see, searched and narrowed by the server, with how many match in all. The same roster as `GET /api/nodes`, for a fleet too large to list whole. Requires `nodes:view`.
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), and `max_running_tasks` caps how many tasks run on it at once, from 0 to 64, where 0 or null removes the cap. Host settings and MicroVM settings require the Org Owner or Org Admin role; NodeLink fields are not accepted here (422). Returns the updated node, or 404 for a node the caller cannot see.
Grow cloud node disk
Grows the boot disk of a node Jaah launched in your own cloud account to `size_gb` (422 for a size not larger); the node grows its filesystem on its next check-in. Requires the Org Owner or Org Admin role and the cloud on your plan (403 otherwise). Returns 202 with the node's `cloud` block.
Change cloud node type
Changes the machine type of a node Jaah launched in your own cloud account, from the cloud's allowed types: the machine stops, changes type and starts again. Requires the Org Owner or Org Admin role and the cloud on your plan (403 otherwise). Returns 202 with the node's `cloud` block, its `change` running.
Get node disk events
Lists the node's disk history, newest first, up to `limit` (default 50): each cleanup it ran with the bytes freed per category, and each time dispatch to it was paused for a full disk or resumed. A node sharing a host's disk also lists the host's cleanups. Returns 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, network, load, swap and pressure series over the last `hours` (default 6), plus its newest reading with its busiest processes. A node that has never reported returns an empty series.
List a node's NodeLinks
Lists the NodeLinks of the node's own organization that the node can mount. Each says whether it is attached to this node, where it lands on this node, and its mount state: `mounted`, `not_mounted` with a reason, `needs_permission` with what to grant on a Mac, or `unknown` until the node reports it. Requires permission to view nodes.
Set a node's NodeLinks
Sets exactly which NodeLinks the node mounts, and the node mounts or unmounts them straight away. A NodeLink of another organization returns 404; attaching needs the plan to include NodeLink, while detaching always works. Requires the Org Owner or Org Admin role.
Get node placement groups
Lists the node groups a node is in. Requires `nodes:view`; returns 404 for a node the caller cannot see.
Set a node's groups
Replaces the node groups a node is in, with the same 409 confirmation as a group's member change. Requires `nodes:edit` and the Node groups plan feature.
Get node sessions usage
Returns the sessions running now on the node and on every node co-located on it that you can see, each with its CPU, memory and process count, largest memory first.
List placement groups
Lists the organization's node groups by name, each with its description, member count, first three member names and the projects that run on it, after the built-in All group and its node count. Requires `nodes:view`.
Create placement group
Creates a node group, optionally with member nodes; names are unique in the organization (any letter case) and All is built in (422 naming the field). Requires `nodes:edit` and the Node groups plan feature (403 otherwise). Returns the group with its members and projects.
Delete placement group
Deletes a node group; a project left with no group runs on all nodes. If projects use it, returns 409 naming them until called with `confirm=true`. Requires `nodes:edit`; works even when the plan no longer includes Node groups.
Get placement group
Returns one node group with its members, each with its status, and the projects that run on it. Requires `nodes:view`; another organization's group is a 404.
Update node group
Renames, describes or replaces the members of a node group. A member change that takes a node away from a project whose tasks are using it returns 409 listing those nodes until it is sent again with `confirm`; running tasks finish where they are. Requires `nodes:edit` and the Node groups plan feature.
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.
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.