Managing Nodes#

Everything in LabTether starts with nodes — the machines you want to see, reach, and keep healthy. This page covers the full lifecycle: installing an agent, getting a node enrolled, diagnosing problems, and cleaning up nodes you no longer need.

Installing agents#

The agent is a lightweight binary that runs on each managed machine. It phones home to your hub, reports telemetry, and enables terminal, desktop, and file operations.

Always copy the install command from the LabTether UI (Settings → Enrollment or the Add Device flow). The generated command prompts you to paste the separately displayed one-time token, keeping it out of shell history and process arguments.

Linux#

curl --proto '=https' --tlsv1.2 -fsSLo labtether-install.sh https://hub.example.com/install.sh
read -r -s -p 'Paste enrollment token: ' token; printf '\n'
token_file="$(mktemp)"; chmod 600 "$token_file"
printf '%s\n' "$token" > "$token_file"; unset token
sudo bash labtether-install.sh --enrollment-token-file "$token_file"
rm -f "$token_file" labtether-install.sh

The installer prints colored, step-by-step progress in interactive terminals — hostname, fingerprint, and key settings all get a highlighted summary at the end. If you pipe it somewhere, output falls back to plain text.

If your hub uses Tailscale HTTPS (the recommended path), the command targets the publicly-trusted https://<host>.<tailnet>.ts.net origin. If you pick a direct LabTether TLS target instead, the generated command switches to a pinned bootstrap.sh endpoint so the node can trust the LabTether CA before the main install runs.

Desktop prerequisites are included by default with --install-vnc-prereqs (alias: --auto-install-vnc). This installs x11vnc, Xvfb, xterm, xdotool, and the GStreamer runtime needed for WebRTC and audio paths.

Low-power mode — for a Raspberry Pi or any node where you want the absolute minimum idle footprint:

curl --proto '=https' --tlsv1.2 -fsSLo labtether-install.sh https://hub.example.com/install.sh
read -r -s -p 'Paste enrollment token: ' token; printf '\n'
token_file="$(mktemp)"; chmod 600 "$token_file"
printf '%s\n' "$token" > "$token_file"; unset token
sudo env \
  LABTETHER_LOW_POWER_MODE=true \
  LABTETHER_LOG_STREAM_ENABLED=false \
  bash labtether-install.sh --enrollment-token-file "$token_file"
rm -f "$token_file" labtether-install.sh

You can still override specific intervals later:

sudo env \
  LABTETHER_LOW_POWER_MODE=true \
  AGENT_COLLECT_INTERVAL=30 \
  AGENT_HEARTBEAT_INTERVAL=120 \
  systemctl restart labtether-agent

Verify: systemctl status labtether-agent and journalctl -u labtether-agent -n 100 --no-pager.

Restart: sudo systemctl restart labtether-agent.

Uninstall:

# Keep identity files (re-enroll later)
sudo labtether agent uninstall

# Remove everything
sudo labtether agent purge

Tip: If the node was installed before the newer systemd unit shipped, rerun the installer to refresh the service file. Older units used ProtectSystem=full, which blocks apt/dpkg writes and prevents agent self-update.

macOS#

Copy the enrollment command from the UI. If you use the native app wrapper, make sure the bundled helper binary is present.

Verify:

launchctl list | rg -i labtether
log show --last 10m --predicate 'eventMessage CONTAINS[c] "labtether"'

Restart:

launchctl kickstart -k gui/$(id -u)/com.labtether.agent

Windows#

Open PowerShell as Administrator and paste the enrollment command from the UI.

Verify:

Get-Service -Name *labtether*
Get-WinEvent -LogName Application -MaxEvents 100 | Where-Object { $_.Message -match 'labtether' }

Restart:

Restart-Service -Name labtether-agent

FreeBSD#

FreeBSD endpoint enrollment is not part of the current public release contract, and no FreeBSD agent artifact is published. To track a FreeBSD host today, add it as a Manual Device and configure a generic protocol such as SSH. Native telemetry, service management, package updates, and rc.d installation remain planned; follow Platform Support for status.

Installer options in Add Device#

The Add Device → Agent flow shows common controls inline:

• File access scope — home directory only, or full disk access
• Desktop prerequisites — auto-install VNC/WebRTC dependencies
• Automatic agent updates — keep the agent self-updating

Use Advanced settings only for uncommon overrides like Docker discovery tuning, force-update, or tokenless/pending-approval installs.

Approving and enrolling nodes#

After the agent installs and connects, it appears in the Pending Agents list in your console.

1. Open the pending list and verify the hostname and fingerprint match the machine you just set up.
2. Approve the node.
3. The node moves to your inventory, starts reporting telemetry, and becomes available for terminal/desktop/file workflows.

Auto-enrollment with tokens — if you generated the install command from the UI with a valid enrollment token, the node can enroll automatically without manual approval. This is the fastest path for batch installs.

Tokenless installs — under Advanced settings, you can run the installer without a token. The agent connects and waits in the pending list until you manually approve it. Useful when you want a human gate on every new node.

Tip: If the selected connection target uses Tailscale HTTPS, enrolled agents automatically receive the https://<host>.<tailnet>.ts.net hub URL, so they connect over the trusted path end-to-end without falling back to localhost origins.

Triaging node issues#

When a node shows an unhealthy status or drops offline, here is a fast diagnostic loop:

1. Check the status badge and alerts. The node detail page shows current state, group membership, and any firing alerts.

2. Look at the recent timeline. Log spikes, metric anomalies, and recent actions tell you what changed.

3. Validate connectivity. Check the agent heartbeat and last-seen timestamp. If the agent has not checked in, the problem is likely network or agent-process level.

4. Run focused diagnostics. Open the System panel to check CPU, memory, storage, and network at a glance. Then pivot to a terminal session for quick checks — df -h, free -m, top, ss -tlnp.

5. Check dependencies. Use the topology and services views to see if upstream or downstream systems are also affected. In the node-detail cluster topology graph, verify guest-to-host runs_on links in the mapping editor before applying fixes.

6. Fix and record. Apply the fix, verify recovery, and log notes in an incident if the issue warrants tracking.

Tip: If a node goes offline and you cannot reach it via terminal, check whether it responds to ping or SSH from another machine on the same network. The issue may be agent-specific rather than system-wide. See Node Offline for deeper troubleshooting.

Renaming and removing nodes#

Rename: Open the node detail page, go to Agent Settings → Device Name, and set the new display name. The rename takes effect immediately in all views.

Remove: Delete the node from your inventory when it is decommissioned. This removes it from all views, topology maps, and alert scoping. If you want the option to re-enroll the same machine later, use labtether agent uninstall (keeps identity files) rather than labtether agent purge.

Manual devices#

Not everything runs an agent. Network switches, IoT devices, legacy systems, and appliances can be added as manual devices so they still appear in your inventory and support terminal or desktop access.

1. Click Add Device on the Devices page and select Manual Device.
2. Enter a name, IP/hostname, and platform (Linux, Windows, macOS, FreeBSD, or other).
3. Click Create.

After creating the device, open its detail page and configure protocols in the Protocols panel:

For SSH, you can use password auth, SSH key auth, or credential profiles. LabTether generates an Ed25519 key pair for the hub — when you add SSH to a manual device, it offers to install the public key on the target so future connections are passwordless. View the hub public key at Settings → SSH Hub Key.

Use Test Connection after configuring a protocol to verify connectivity before you rely on it.

Tip: Manual devices with SSH or Telnet appear in the terminal workflow. Manual devices with VNC, RDP, or ARD appear in remote desktop. Protocol routing priority is: protocol config (Protocols panel) → terminal config (legacy fallback) → agent connection.

For managing credentials across many devices, create profiles at Settings → Credentials (e.g., "Linux SSH Key", "Network Switch Telnet") and assign them when configuring device protocols. Supported credential types: SSH password, SSH private key (with optional passphrase), Telnet password, and RDP password.