agent: add cli session shim and remote install/repair workflows

Author: AndreyMarchuk

.env.schema

@@ -54,6 +54,14 @@ SLACK_ALLOWED_USERS=
 # @sensitive=false @type=number
 BAUDBOT_EXPERIMENTAL=0
 
+# ── Dev Agent Backend ────────────────────────────────────────────────────────
+
+# Default backend for spawning dev agents.
+# Control-agent may override per-task.
+# Options: pi, claude-code, codex, auto
+# @sensitive=false @type=string
+DEV_AGENT_BACKEND=pi
+
 # ── Email Monitor (experimental-only) ───────────────────────────────────────
 
 # AgentMail API key (only used when BAUDBOT_EXPERIMENTAL=1)

CONFIGURATION.md

@@ -68,6 +68,12 @@ Email tooling is disabled by default. To enable it, run setup/install in experim
 
 ## Optional Variables
 
+### Dev Agent Backend
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEV_AGENT_BACKEND` | Default backend for spawning dev agents (`pi`, `claude-code`, `codex`, `auto`) | `pi` |
+
 ### Sentry Integration
 
 | Variable | Description | How to get it |
@@ -149,6 +155,28 @@ Set during `setup.sh` / `baudbot install` via env vars:
 | `GIT_USER_NAME` | Git commit author name | `baudbot-agent` |
 | `GIT_USER_EMAIL` | Git commit author email | `baudbot-agent@users.noreply.github.com` |
 
+### Remote CLI (operator-local, not runtime)
+
+These apply only to `baudbot remote ...` when run from your local operator machine. They are not part of agent runtime `.env` and should not be written to `/home/baudbot_agent/.config/.env`.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BAUDBOT_REMOTE_DIR` | Local state directory for remote targets/checkpoints/keys | `~/.baudbot/remote` |
+| `HETZNER_API_TOKEN` | Hetzner token fallback for `--hetzner-token` | *(empty)* |
+| `TAILSCALE_AUTHKEY` | Tailscale auth key fallback for `--tailscale-auth-key` | *(empty)* |
+| `REMOTE_BOOTSTRAP_URL` | Bootstrap script URL used by remote install step | `https://github.com/modem-dev/baudbot/main/bootstrap.sh` |
+| `REMOTE_TAILSCALE_INSTALL_URL` | Tailscale install script URL used by remote workflow | `https://tailscale.com/install.sh` |
+| `REMOTE_TAILSCALE_WAIT_ATTEMPTS` | Tailscale readiness polling attempts after `tailscale up` | `40` |
+| `REMOTE_TAILSCALE_WAIT_INTERVAL_SEC` | Delay between Tailscale readiness polls | `3` |
+| `REMOTE_CHECKPOINT_MAX_RETRIES` | Retries per install checkpoint before interactive escalation | `3` |
+| `REMOTE_HETZNER_SERVER_TYPE` | Hetzner default server type for remote install | `cpx11` |
+| `REMOTE_HETZNER_IMAGE` | Hetzner default image for remote install | `ubuntu-24.04` |
+| `REMOTE_HETZNER_LOCATION` | Hetzner default location for remote install | `ash` |
+| `REMOTE_HETZNER_WAIT_TIMEOUT_SEC` | Timeout while waiting for server running state | `600` |
+| `REMOTE_HETZNER_WAIT_INTERVAL_SEC` | Poll interval while waiting for server running state | `5` |
+| `REMOTE_SSH_REACHABLE_ATTEMPTS` | SSH readiness attempts per checkpoint | `40` |
+| `REMOTE_SSH_REACHABLE_INTERVAL_SEC` | Delay between SSH readiness attempts | `3` |
+
 ### Heartbeat
 
 | Variable | Description | Default |

README.md

@@ -83,6 +83,27 @@ Upgrade later:
 sudo baudbot update
 ```
 
+Remote provisioning/install and repair (operator-run from your local machine):
+
+```bash
+# Provision on Hetzner and install Baudbot
+baudbot remote install --mode hetzner --target team-bot
+
+# Install on an existing host
+baudbot remote install --mode host --target team-bot --host 203.0.113.10 --ssh-user root
+
+# Install + connect host to Tailscale
+baudbot remote install --mode host --target team-bot --host 203.0.113.10 --tailscale
+
+# Resume an interrupted run
+baudbot remote resume team-bot
+
+# Guided repair for an existing target
+baudbot remote repair --target team-bot
+```
+
+`baudbot remote` persists checkpoints in `~/.baudbot/remote/targets/*.json`, so interrupted installs can resume from the next incomplete checkpoint.
+
 Install with a specific pi version (optional):
 
 ```bash

bin/baudbot

@@ -138,6 +138,7 @@ usage() {
   echo "  install        Bootstrap install from GitHub (download script, then escalate)"
   echo "  setup          One-time system setup (user, deps, firewall, systemd; --experimental enables risky integrations)"
   echo "  config         Interactive secrets and config setup"
+  echo "  remote         Remote install/repair workflows (Hetzner or existing host)"
   echo "  env            Manage env vars and backend source (set/get/sync/backend)"
   echo "  deploy         Deploy source + config to agent runtime"
   echo "  broker         Slack broker commands (register workspace linkage)"
@@ -411,6 +412,11 @@ case "${1:-}" in
     exec "$BAUDBOT_ROOT/bin/config.sh" "$@"
     ;;
 
+  remote)
+    shift
+    exec "$BAUDBOT_ROOT/bin/remote.sh" "$@"
+    ;;
+
   env)
     shift
     exec "$BAUDBOT_ROOT/bin/env.sh" "$@"

bin/baudbot.test.sh

@@ -191,6 +191,35 @@ EOF
   )
 }
 
+test_remote_dispatches_to_remote_script() {
+  (
+    set -euo pipefail
+    local tmp out
+    tmp="$(mktemp -d /tmp/baudbot-cli-test.XXXXXX)"
+    trap 'rm -rf "$tmp"' EXIT
+
+    mkdir -p "$tmp/bin/lib"
+    printf '{"version":"1.2.3"}\n' > "$tmp/package.json"
+    cat > "$tmp/bin/lib/baudbot-runtime.sh" <<'EOF'
+#!/bin/bash
+cmd_status() { :; }
+cmd_logs() { :; }
+cmd_sessions() { :; }
+cmd_attach() { :; }
+has_systemd() { return 0; }
+EOF
+
+    cat > "$tmp/bin/remote.sh" <<'EOF'
+#!/bin/bash
+echo "remote-dispatch-ok:$*"
+EOF
+    chmod +x "$tmp/bin/remote.sh"
+
+    out="$(BAUDBOT_ROOT="$tmp" bash "$CLI" remote list)"
+    [ "$out" = "remote-dispatch-ok:list" ]
+  )
+}
+
 echo "=== baudbot cli tests ==="
 echo ""
 
@@ -199,6 +228,7 @@ run_test "status dispatches via runtime module" test_status_dispatches_via_runti
 run_test "attach requires root" test_attach_requires_root
 run_test "broker register requires root" test_broker_register_requires_root
 run_test "restart kills bridge tmux then restarts systemd" test_restart_restarts_systemd_and_kills_bridge_tmux
+run_test "remote command dispatches to remote.sh" test_remote_dispatches_to_remote_script
 
 echo ""
 echo "=== $PASSED/$TOTAL passed, $FAILED failed ==="

bin/broker-register.test.mjs

@@ -189,7 +189,7 @@ test("registerWithBroker sends registration_token when provided", async () => {
   });
 });
 
-test("runRegistration integration path succeeds against live local HTTP server", async () => {
+test("runRegistration integration path succeeds against live local HTTP server", async (t) => {
   const brokerPubkey = Buffer.alloc(32, 5).toString("base64");
   const brokerSigningPubkey = Buffer.alloc(32, 6).toString("base64");
 
@@ -222,7 +222,21 @@ test("runRegistration integration path succeeds against live local HTTP server",
     res.end(JSON.stringify({ ok: false, error: "not found" }));
   });
 
-  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  try {
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error) {
+      const code = String(error.code || "");
+      if (code === "EPERM" || code === "EACCES") {
+        t.skip("Localhost bind is not permitted in this environment");
+        return;
+      }
+    }
+    throw error;
+  }
   const address = server.address();
   const brokerUrl = `http://127.0.0.1:${address.port}`;