p24-infra Docs

dev-workstation-remote-control-persistence

4 min read

Playbook: Keep a Remote Control session persistently reachable on dev-workstation

Why this exists: 2026-09 — administration.env.sops could not be rekeyed for lap2/lap2-wsl (#6861) because dev-workstation, the sole host holding a working decrypt key for that file, became unreachable: no CF Tunnel exists to it (it’s a human-interactive workstation, not a managed worker — see docs/environments/dev-workstation.md), and no Remote Control session was alive to run the one-off sops-set.ps1 -RekeyOnly command remotely. A previously-used Remote Control session (“p24-infra repos setup for lap2”) had gone offline and could not be revived without physically being at the machine. This playbook is the fix: keep at least one Remote Control session continuously reachable on dev-workstation so this class of lockout can’t recur.

Source of the technical claims below: Claude Code’s own Remote Control documentation (verified via the claude-code-guide agent, 2026-09-09) — not reverse-engineered or guessed.

What actually causes “offline”

  • Remote Control connects outbound-only (HTTPS to Anthropic’s API, no inbound ports). Sleep or a dropped network connection does not take a session offline — it reconnects automatically when the machine/network comes back, queuing messages in the meantime.
  • “Offline” means the local claude process itself exited — terminal closed, app quit, process crashed, or the machine was shut down/logged out.
  • Interactive mode (claude --remote-control) retries reconnecting indefinitely. Server mode (claude remote-control) gives up and exits after ~10 minutes of no network.

So the actual failure mode to defend against is the process dying, not sleep or a flaky connection.

Steps to run at the next dev-workstation access window

Run these on dev-workstation itself (PowerShell, admin not required for steps 1-2):

  1. Enable Remote Control by default for every interactive session. Edit %USERPROFILE%\.claude\settings.json and add:

    {
  "remoteControlAtStartup": true
}

    This does not by itself keep a process running after the terminal closes — it just means any claude session started there automatically exposes Remote Control, so a human sitting down to use the machine normally doesn’t have to remember the flag.

  2. Keep a session alive continuously, since closing the terminal is the actual failure mode. There’s no Windows-native tmux/screen equivalent shipped with Claude Code and no officially documented Windows auto-start mechanism — this step is a DIY Task Scheduler wrapper:

    • Create a Scheduled Task (“At log on” trigger, running as the dev-workstation user, not SYSTEM — Remote Control needs the user’s own Claude Code auth) that launches: 
      wt.exe -w 0 nt -d "C:\devWork\p24-infra" powershell -NoExit -Command "claude --remote-control"
      (wt.exe keeps a visible Windows Terminal tab so the session isn’t invisible/unmanageable; a fully hidden/headless run is possible via -WindowStyle Hidden but makes it hard to notice if something needs attention).
    • In the task’s Settings tab: enable “If the task fails, restart every: 1 minute”, attempts “3” (or higher) — this covers a crash of the claude process itself.
    • In Conditions: uncheck “Start the task only if the computer is on AC power” and “Stop if the computer switches to battery power” if this is a laptop that may run on battery.
    • In Power settings on the machine: prevent sleep-on-lid-close if this needs to survive being closed (powercfg /change standby-timeout-ac 0; note this is a tradeoff against battery/thermal — don’t apply it to a machine that needs to actually sleep for other reasons).

  3. Verify: from another device, confirm the session shows as reachable (not offline) in the Remote Control session list. Leave it running and re-check after a sleep/wake cycle and after a deliberate taskkill of the claude process, to confirm the Task Scheduler restart trigger actually recovers it.

Security tradeoff — read before enabling

dev-workstation is the sole recipient with a working decrypt key for secrets/administration.env.sops (the most sensitive secrets file in this repo — CF Global Key, MongoDB rs0 admin, Wasabi admin IAM, GCP SA key, GITLAB_ADMIN_PAT, SUPABASE_ACCESS_TOKEN, IONOS/OVH API, see CLAUDE.md §SOPS file map). Keeping a Remote Control session always-reachable on it is a deliberate widening of that machine’s attack surface:

  • The channel itself is outbound-only/TLS with short-lived, single-purpose credentials — Claude Code’s own security model. No inbound port is opened.
  • Session transcripts are stored on Anthropic’s servers to support cross-device sync and reconnection. This is inherent to how Remote Control works, not a misconfiguration.
  • Anyone with access to the developer’s Anthropic account gains remote command execution on the machine holding the admin secrets key.

This is an explicit owner decision, not something to roll out silently — re-confirm it’s still wanted before implementing if this playbook is picked up much later than 2026-09.

  • docs/environments/dev-workstation.md — the machine this applies to
  • docs/environments/lap2.md / lap2-wsl.md §Open Items — the pending administration.env.sops rekey this unblocks
  • .sops.yaml — current recipient list for secrets/administration.env.sops (developer, windows-dev-radieu, lap2, lap2-wsl as of #6861)

Graph View