Remote Hosts

Read the host placement policy

Placement decides where the organization's virtual worker containers run: on Backbuild's cloud (`cloud`), on any of its hosts (`all_hosts`), on the hosts in one group (`pool`), or on chosen hosts (`hosts`), optionally falling back to the cloud when none is ready. A worker can also be pinned to one host. Changes apply at each worker's next container start; running containers are not moved. Part of Container Operations, which needs Containers to be on for the organization. Returns the policy, the hosts with whether each is ready and how many containers it runs, the groups that can serve as pools, and each worker's placement: pinned or following the policy, where its next container would start and why, and where its current one runs. Requires the permission to manage containers or container policy.

Auth Session JWT (Bearer)

Responses

Change the host placement policy

Placement decides where the organization's virtual worker containers run: on Backbuild's cloud (`cloud`), on any of its hosts (`all_hosts`), on the hosts in one group (`pool`), or on chosen hosts (`hosts`), optionally falling back to the cloud when none is ready. A worker can also be pinned to one host. Changes apply at each worker's next container start; running containers are not moved. Part of Container Operations, which needs Containers to be on for the organization. `pool_id` goes with `pool`, and `host_ids` (1 to 50) with `hosts`. The answer counts workers pinned to a host the new policy no longer includes. Recorded in the audit log with the policy before and after. Requires the permission to manage container policy.

Auth Session JWT (Bearer)

Request Body

{
  "mode": "pool",
  "pool_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f02",
  "fallback_to_cloud": true
}

Responses

Clear every worker's host pin

Clears the host pin of every virtual worker in the organization, so each follows the placement policy again from its next container start. Recorded in the audit log. Requires the permission to manage virtual workers.

Auth Session JWT (Bearer)

Responses

List hosts

Lists the organization's Remote Hosts with their status, agent version and update state, Docker state, last heartbeat and capacity. Revoked hosts are left out unless `include_revoked=true`. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Get a host

Returns one host. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Turn a host's Docker role on or off

Turns the Docker role on or off. With it on, the agent installs and runs Docker on its next check-in and the host can run the organization's containers and virtual workers; turning it off stops new placements but does not remove Docker from the machine. Recorded in the audit log. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "docker_enabled": true
}

Responses

Drain a host

Puts a running host in `draining`: it takes no new containers while what is already running finishes, so you can reimage or service it. Draining a draining host changes nothing. Recorded in the audit log. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Revoke a host

Removes a host from the organization for good: its unfinished jobs are marked orphaned (`orphaned_jobs`) and its private connection is torn down so the host can no longer reach Backbuild. `tunnel_teardown` reports whether the connection was removed; when it reads `failed`, revoke again to retry. Revoking a revoked host changes nothing. Recorded in the audit log. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Check a host's connection

Reports whether the host's private connection to Backbuild is set up and routed, its private address, and its live health: the connection status, how many agents are connected, and whether more than one machine is using the same connection (for example a cloned machine). Health is advisory: when it cannot be read, `health` is null and `health_error` says why, and the rest of the answer still stands. At most 60 checks a minute per organization. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Return a drained host to service

Moves a draining host back to `running`, so it takes new containers again; a running host stays as it is. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Get the host agent install command

Returns the Linux install command for the Backbuild host agent and its download addresses for x64 and arm64, with each file's SHA-256, for the agent version this organization uses (its pinned version when it pins one, else the current release). The command checks the download's hash before installing. Without a pairing code the agent shows a code and a confirmation secret on the host to approve with `POST /v1/docker-hosts/device/approve`; for a one-step pairing use `POST /v1/docker-hosts/pair-token` instead. Any signed-in member can read it: the command alone joins nothing until someone with the permission approves the host.

Auth Session JWT (Bearer)

Responses

Read the agent update policy

Returns the organization's agent update policy (automatic updates on or off, and an optional pinned version) and, for each host, its own override, the policy in effect for it, its current agent version and its last update error. By default updates are on with no pin. A pin holds hosts at that version: agents never downgrade, so a pin older than a host's version keeps that host where it is. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Responses

Change the agent update policy

Without `host_id`, changes the organization's policy (`auto_update`, `pinned_version`); with `host_id`, changes that host's override (`mode`: `inherit` follows the organization, `auto` or `off`; `pinned_version`). A field you leave out stays as it is; `pinned_version: null` clears a pin. Recorded in the audit log with the values before and after. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Request Body

{
  "auto_update": true,
  "pinned_version": null
}

Responses

Approve a host

Enrolls a host that is waiting for approval. Send the code the host shows and, unless the host came from your own pairing command (`via_pair_token: true`), the confirmation secret shown on the host's console, which proves you can see the machine. Choose its name, an optional region label, and whether it takes the Docker role (on by default). The new host starts as `pending` while its secure connection is set up. Every approval is recorded in the audit log with the approver, the fingerprint and the address. Requires the permission to add Remote Hosts (owners and admins hold it), a session that completed its second factor, and a second-factor check within the last 10 minutes.

Auth Session JWT (Bearer)

Request Body

{
  "user_code": "KQ7M-2XWP",
  "confirm_secret": "4F9C2A",
  "name": "build-01",
  "region": "us-east",
  "docker_enabled": true
}

Responses

List hosts waiting for your approval

Lists hosts that ran a pairing command for this organization but still need a person to approve them, with what to check before approving: the host's label, its key fingerprint, the address it connected from, and its code. Never returns the host's secrets. Requires the permission to add Remote Hosts.

Auth Session JWT (Bearer)

Responses

List firewall rules

Lists the inbound allow rules the agent applies to the organization's hosts. A rule applies at one of three scopes: every host (`global`), the hosts in one group (`host_group`), or a single host (`host`). A host allows the union of the rules that apply to it. With `host_id`, lists only the rules that apply to that host. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Add a firewall rule

Allows inbound traffic from a CIDR range to a port. A rule applies at one of three scopes: every host (`global`), the hosts in one group (`host_group`), or a single host (`host`). A host allows the union of the rules that apply to it. The agent picks up the change on its next check-in. Recorded in the audit log. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Request Body

{
  "scope": "host_group",
  "host_group_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f01",
  "cidr": "203.0.113.0/24",
  "port": 22,
  "proto": "tcp",
  "description": "Office SSH"
}

Responses

Remove a firewall rule

Removes a rule. Recorded in the audit log. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

List host groups

Lists the organization's host groups with their members. A group is a pool for container placement and a target for firewall rules and managed accounts. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Responses

Create a host group

Creates an empty group. Names are unique in the organization. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Request Body

{
  "name": "gpu-pool",
  "description": "Hosts with GPUs"
}

Responses

Delete a host group

Deletes a group and its membership list (the hosts themselves are untouched). A group still used by firewall rules, managed accounts or the container placement policy cannot be deleted until those are changed (`IN_USE`). Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Add a host to a group

Adds a host to a group; adding a member again changes nothing. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Request Body

Responses

Remove a host from a group

Removes a host from a group. Requires the permission to manage Remote Hosts in the organization; owners and admins hold it, members do not.

Auth Session JWT (Bearer)

Parameters

Responses

Create a one-step pairing command

Creates a single-use pairing code and returns the install command with the code built in. Run the command on the host (as root, or a user that can use sudo); the host then joins this organization with no further approval. The code works once and expires after 10 minutes; it is shown only in this answer. A host paired this way starts with no serving role: turn on its Docker role with `POST /v1/docker-hosts/{id}/docker`. If pairing cannot complete automatically, the host waits for approval (see `GET /v1/docker-hosts/device/pending`). Requires the permission to add Remote Hosts (owners and admins hold it), a session that completed its second factor, and a second-factor check within the last 10 minutes.

Auth Session JWT (Bearer)

Responses

List managed account rules

Lists the rules that give people operating-system accounts on the organization's hosts. Each rule maps a person, group, department or role to all hosts, a host group or one host, with the account's options: a home directory, the login shell, sudo, membership of the Docker group, and whether the person's SSH sources are added to the host firewall. Every host applies changes within about 30 seconds: accounts are created for people a rule now covers, and locked for people it no longer covers or who leave the organization or are deactivated. Requires the permission to provision Remote Host accounts (owners and admins hold it).

Auth Session JWT (Bearer)

Responses

Add a managed account rule

Adds a rule. Sudo and Docker group membership can be granted only to a single person, never to a group, department or role (`INVALID_GRANT`). Editing these rules needs a session that completed its second factor. Recorded in the audit log. Requires the permission to provision Remote Host accounts.

Auth Session JWT (Bearer)

Request Body

{
  "principal_type": "user",
  "principal_user_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f01",
  "target_type": "host_group",
  "target_group_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f02",
  "grant_sudo": false,
  "grant_docker": true,
  "login_shell": "/bin/bash"
}

Responses

Remove a managed account rule

Removes a rule; hosts lock the accounts it no longer grants. Needs a session that completed its second factor. Recorded in the audit log. Requires the permission to provision Remote Host accounts.

Auth Session JWT (Bearer)

Parameters

Responses

Read where a worker runs

Returns the host a virtual worker is pinned to and whether that host can take it now, or null when the worker follows the placement policy. Any active member of the organization can read it.

Auth Session JWT (Bearer)

Parameters

Responses

Pin a worker to a host

Pins a virtual worker to one of the organization's hosts, or clears the pin with `host_id: null`. The host must be running with its Docker role on and, when the policy places workers on hosts, must be one the policy includes (`PLACEMENT_RESTRICTED`). Takes effect at the worker's next container start. Recorded in the audit log. Requires the permission to manage virtual workers.

Auth Session JWT (Bearer)

Parameters

Request Body

{
  "host_id": "0190a6f2-3c1e-7d4b-9a2f-5b6c7d8e9f03"
}

Responses