Remote Hosts

Remote Hosts lets your organization run its containers and virtual workers on Linux machines you own, beside the cloud locations Backbuild provides. This page explains how a host joins, who can manage it, and what the API covers. Every route, with its fields, is in the Remote Hosts endpoint reference; running containers on your own compute from the app is covered in Container Policies and Administration.

Who Can Call It

The routes take a signed-in user’s access token and act in that session’s organization. In the app they live under Settings, then Administration, then Remote Hosts. They are gated by permissions, not by a plan: an organization’s owners and admins can add, manage and provision hosts, and members can do none of it. Adding a host and editing managed accounts also need a session that completed its second factor, and adding a host needs a second-factor check within the last ten minutes. Container placement is part of Container Operations, which needs Containers to be on for the organization and the permission to manage containers or container policy.

How a Host Joins

  1. One step. Create a pairing command with POST /v1/docker-hosts/pair-token and run it on the machine, as root or with sudo. It installs the Backbuild agent, checks the download’s hash, and joins the machine to your organization with no further approval. The pairing code works once and expires after ten minutes.
  2. With an approval. Install the agent with the command from GET /v1/docker-hosts/agent-install. The machine shows a code and a confirmation secret on its console; approve it with POST /v1/docker-hosts/device/approve, which proves you can see the machine. A host that ran your pairing command but could not finish on its own waits in GET /v1/docker-hosts/device/pending for the same approval, without the secret.

A new host is pending while its private connection to Backbuild is set up, then initializing and running. It needs the Docker role to run containers: an approval gives it by default, and a host paired with a command starts without it, so turn it on with POST /v1/docker-hosts/{id}/docker. To service a host, drain it with /fence and bring it back with /unfence; to remove it for good, revoke it, which tears down its connection. Every enrollment, change and revocation is recorded in the audit log.

Placement

The placement policy (/v1/containers/host-placement) decides where virtual worker containers run: Backbuild’s cloud, all your hosts, the hosts in one host group, or hosts you list, optionally falling back to the cloud when none is ready. A single worker can be pinned to a host with /v1/virtual-workers/{id}/run-host. Changes take effect at each worker’s next container start; running containers are not moved.

Firewall, Managed Accounts and Agent Updates

  • Firewall rules allow inbound traffic from a CIDR range to a port, on every host, on a host group, or on one host. A host allows the union of the rules that apply to it.
  • Managed accounts give people operating-system accounts on your hosts by person, group, department or role, with options for the home directory, shell, sudo and the Docker group. Sudo and the Docker group can be granted only to a single person. Hosts apply changes within about thirty seconds and lock the accounts of people who leave or are deactivated.
  • Agent updates are automatic by default. You can turn them off or pin a version for the whole organization or for one host; agents never downgrade.

What Is Not Available Yet

Containers and virtual workers run on your hosts today. Sending a one-off job straight to a host through the API is not available yet, so the reference does not list it.

Where to Go Next