Skip to main content

Agent runbook — bring a host onto Tailscale

Step-by-step procedure for joining a new host to the tailnet so its agent containers can participate in the fleet.

Knowledge entry (read first): Tailscale — verified tailnet facts, the port map, and fleet topology rules. This runbook contains the procedure; that Knowledge page provides its context. There is no separate Reference category. An agent following this runbook should not need to research Tailscale basics.

Scope: one host, agent-container participation only. No Funnel, no public exposure, no ledger/broker/controller on the remote host.

The procedure at a glance (the prose below governs):

Preconditions​

  • Owner has approved this specific host for fleet participation.
  • Owner has generated a tailnet-scoped auth key (admin console) and handed it to the operator channel — never typed into a log, commit, or chat message. Agents must not be shown the key; they may only see a placeholder.
  • The host runs Docker. Agent containers are the only fleet workload here.

Steps​

1. Install the Tailscale client​

curl -fsSL https://tailscale.com/install.sh | sh
systemctl enable --now tailscaled

Exit test: tailscale version prints a version; systemctl is-enabled tailscaled → enabled.

2. Join the tailnet (operator step — needs the auth key)​

The operator, not the agent, performs the join:

tailscale up --authkey="$TS_AUTHKEY" --hostname="<new-host-name>"

Exit test:

tailscale status            # BackendState: Running, self listed
tailscale ip -4             # a 100.x.y.z address assigned

The host must appear in tailscale status on jkdev001 as online.

3. Verify tailnet reachability to the fleet​

From the new host, probe the primary host over the tailnet (no public internet needed):

curl -s -o /dev/null -w '%{http_code}\n' \
  https://jkdev001.tail6817df.ts.net:8445/
# expect 200 — that is the docsite; reaching it proves tailnet transport +
# MagicDNS + serve-proxy all work end to end.

Exit test: HTTP 200. If you get a connection error, check that the host is Running/online in tailscale status on both sides.

4. Validate the container egress design (blocking)​

Stop here unless the owner has supplied and verified a constrained container-to-tailnet gateway and a separate model-provider egress proxy. A Docker --internal bridge prevents external routing. Creating one by itself does not give agent containers a path to jkdev001's tailnet services.

The network design must identify its gateway, approved destinations, DNS, proxy authentication, and explicit denial of direct public-internet egress. Test from a disposable container on the exact proposed network:

  • Approved controller/broker tailnet endpoints are reachable through the defined gateway, with expected authentication.
  • The model-provider proxy is reachable through its approved path.
  • A direct request to a public IP fails; the same request through an approved proxy follows the configured policy.

Preserve commands and actual exit codes in the host onboarding record. If any positive or negative control fails, do not launch an agent container or claim the host is admitted.

5. Point the agent bootstrap at the fleet (only after step 4)​

The agent container image is identical to the local one; only the bootstrap values differ. Use the approved gateway and proxy endpoints, not an assumed direct route from an internal bridge. The registry entry records the host name.

Exit test: after the step-4 path is proven, the controller accepts the host's check-in and the agent claims a task from the shared ledger via the broker.

6. Verify degraded mode works​

Expectation (do not "fix" this): if the host loses tailnet connectivity, the agent continues current work, queues submissions, and replays on reconnect; the watchdog escalates on silent heartbeats. A transient tailnet blip is not an incident.

Rollback / removal​

  • Stop agent containers; remove only the approved container network or gateway that was actually created for this host, after verifying no other workload uses it.
  • tailscale down on the host; owner revokes the auth key and removes the node from the admin console.
  • Remove the host's registry entry from the ledger (owner/coordinator act).

What this runbook must NOT do​

  • Never use Funnel (public exposure) for fleet traffic.
  • Never install or run a ledger, broker, or controller on this host.
  • Never write the auth key into the container, an env file committed to git, or a document.
  • Never force the public internet reachable from agent containers.

Published by Hermes · 2026-10-01.