jackson2w/claude-code-skills / claude-code-remote-control-host
claude-code-remote-control-host
UnverifiedClaude Code Remote Control host
A persistent claude remote-control server on an always-on Linux host, one server process per
project, each a systemd template instance running as a low-privilege service user. Sessions are
created and driven from the Claude mobile app or claude.ai/code; execution and files stay on the
host. Reference build: claude-code (unprivileged Debian 13 LXC, VMID 112, 192.168.50.231),
Terraform claude-code.tf, Ansible claude-code-install.yml + claude-rc-watchdog.sh in
homelab-ansible. Design record: the homelab planning repo's
archive/claude-code-homelab-architecture-proposal.md; state in project_claude_code_rc_host
memory. This skill is the durable "how" and every trap hit building it.
1. Facts that shape the design (verified against the docs and live, 2026-09-09)
- Auth is a browser login, full stop. Remote Control needs the full-scope claude.ai
/login. Aclaude setup-token/CLAUDE_CODE_OAUTH_TOKENcredential is refused by design ("can only make model requests");ANTHROPIC_API_KEYdisqualifies it too. So a headless host needs one interactive step by the account owner, as the service user, over SSH:claude,/login(paste the code the browser shows), finish onboarding,/exit. Plan for it; don't try to script around it. - Two more one-time prompts exist: the workspace-trust dialog per project directory, and
"Enable Remote Control? (y/n)" on the first
claude remote-control. Trust can be pre-seeded (§3); the RC confirmation is answered once interactively (claude remote-controlonce,y, Ctrl+C) and then remembered. - The login expires. In
~/.claude/.credentials.json,claudeAiOauth.expiresAtis the ~8-hour access token (auto-refreshed while a server runs);claudeAiOauth.refreshTokenExpiresAtis the real login lifetime (~28 days observed). Alert on the second. A server that outlives the login stops making progress silently. - The process runs fine without a TTY — probed: it gets as far as the login check headless. Under systemd it works with no pty wrapper.
claude remote-control --helphangs on a signed-in machine: it checks eligibility and starts the server rather than printing help. Take the flag list from the docs page (https://code.claude.com/docs/en/remote-control). Flags go afterremote-control; the useful ones are--name,--capacity N(default 32),--spawn same-dir|worktree|session,--permission-mode.- Outbound-only. Registers with the Anthropic API and polls; no inbound port, no Tailscale
Serve endpoint to create — a documented exception to a "Serve is the standard access pattern"
rule, not a deviation. Direct
api.anthropic.comonly (noANTHROPIC_BASE_URL, no Bedrock). - Don't set
DISABLE_TELEMETRY,DO_NOT_TRACK,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, orDISABLE_GROWTHBOOKfor the service user — each silently disqualifies Remote Control. - Restarting the unit resumes its relay sessions (within ~4h of the stop). Verified: a restart brought the same session back on the phone. Crashed sessions (not the server) are re-served when a device sends them a message.
- No crash auto-recovery of the server itself, and the server exits after ~10 minutes of lost
API reachability. systemd
Restart=alwayscovers both — but not past the start limit. WithStartLimitBurst=6in 30 min atRestartSec=30s, any network outage longer than ~3.5 min leaves every serverfailedfor good: after the 2026-09-27 UniFi cutover all three sat dead for 20 h. Pair the limit with a recovery timer (below). Don't reach forRestartSteps=/RestartMaxDelaySec=backoff instead: its counter (NRestarts) resets only on a manual start, so weeks of routine relay drops would push every restart to the maximum delay.
2. Host shape
- Dedicated service user (
claude,/home/claude, bash shell). Native installer run as that user (curl -fsSL https://claude.ai/install.sh | bash,creates: ~/.local/bin/claude). Debian 13 LXC template has nosudo— install it before anybecome_usertask. ~/projects/<name>per project;git cloneneeds the service user's own SSH key accepted on GitHub (account key = every repo; deploy keys are one-key-per-repo, so that's N keypairs +Hostaliases). Pin GitHub's host key and assert the scanned fingerprint against the published one (SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU) before writing it.- Service user's global
~/.claude/CLAUDE.mdcarries the session-hygiene rules (resume not restart,/compactat breakpoints,/rename, the env-var bans above) so they re-establish every session. ~/.ssh/configfor the service user: right login per fleet host,StrictHostKeyChecking accept-newso a first connection never stalls a phone-driven session.
3. Per-project systemd template unit
[Unit]
Description=Claude Code Remote Control server for project %i
After=network-online.target tailscaled.service systemd-resolved.service
Wants=network-online.target
ConditionPathExists=/home/claude/.claude/.credentials.json
ConditionPathIsDirectory=/home/claude/projects/%i
StartLimitIntervalSec=30min
StartLimitBurst=6
[Service]
User=claude
Group=claude
WorkingDirectory=/home/claude/projects/%i
Environment=HOME=/home/claude
Environment=PATH=/home/claude/.local/bin:/usr/local/bin:/usr/bin:/bin
Environment=LANG=en_US.UTF-8
ExecStart=/home/claude/.local/bin/claude remote-control --name %i --capacity 8
StandardOutput=null
StandardError=journal
Restart=always
RestartSec=30s
KillMode=mixed
TimeoutStopSec=30s
[Install]
WantedBy=multi-user.target
Recovery for instances that hit the start limit — claude-rc-recover.service (oneshot) +
.timer (OnBootSec=10min, OnUnitActiveSec=15min), in homelab-ansible's
claude-code-install.yml:
for u in $(systemctl list-units "claude-rc@*" --state=failed --plain --no-legend | cut -d" " -f1); do
systemctl is-enabled --quiet "$u" || continue # a unit stopped by hand is inactive, not failed
systemctl reset-failed "$u"; systemctl start --no-block "$u"
done
A broken state (expired login) then costs one burst of ≤6 attempts per 15 min, not a 30 s loop,
and a transient outage heals within 15 min of the network returning. The watchdog on
ansible-ctrl re-alerts a persisting failure every 6 h, so a dead server can't sit unnoticed.
ConditionPathExistson the login file keeps instances inactive (a skip, not failed, not restart-looping) until the owner's login exists. Enable them in Ansible withoutstate: started; a separate task starts themwhenthe login file exists.- Do NOT gate on
projects/%i/.git. A server over an empty directory is still a usable session; gating on the checkout took a live server down mid-use. Report "no checkout yet" from the watchdog instead. StandardOutput=nullis load-bearing. With stdout not a TTY the status panel redraws continuously — measured ~5 journal lines/second, ~400k/day. Errors (including the login-expired message) go to stderr and stay in the journal.- Pre-seed workspace trust so a TTY-less server can start in each directory: set
projects["<abs dir>"].hasTrustDialogAccepted = truein~/.claude.json(a small Python script that edits only that key, printschanged/unchanged). Ansiblechanged_whenmust test the last line exactly —'changed' in stdoutalso matches "unchanged". - Default permission mode is the human backstop: every command a phone-driven session runs
prompts on the phone. Enable Push when actions required in
/configso the prompt is a notification. Changing--permission-modeis a deliberate playbook edit, never a session's.
4. Watchdog (report-only, diff-alert)
claude-rc-watchdog.sh on the controller, every 15 min, one SSH round-trip as root:
- Enabled instances: read the
/etc/systemd/system/multi-user.target.wants/claude-rc@*.servicesymlinks. Enabled template instances do not appear insystemctl list-unit-files, and never-started ones aren't loaded forlist-units. - Per unit:
systemctl show -p ActiveState -p SubState -p NRestartswithout--valueand parseKey=Value.--valueprints properties in systemd's internal order, not the requested order — a positionalread a s nsilently gotNRestartsina. - Login:
jq -r .claudeAiOauth.refreshTokenExpiresAt(only that field — never the tokens); fail if past, warn <3 days (matches Claude Code's own warning).expiresAt>2h past with a server running = refresh failing (warn). Alsojournalctl -u 'claude-rc@*' --since '20 min ago' | grep -ci 'login expired\|run /login\|must be logged in'— the most direct signal. - Restart bursts:
NRestartsgrew since the last snapshot → warn (crash or relay drop). - Inactive unit: with no login → ok "waiting on login"; with login but no
.git→ warn "no checkout"; otherwise fail. Alert only on new/worsened findings; silent on recovery.
5. Fleet exec access for the service user (if wanted)
- Grant via the fleet baseline playbook with one
authorized_keytask, a singleclaude_code_pubkeyvar and apresent/absentswitch (revocation = one edit, one run). Targetuser: "{{ ansible_user }}"so it lands on root for the LXC/VM fleet and the admin account on a hand-built host. - Exclude the RC host itself (
when: inventory_hostname != 'claude-code') — otherwise the unprivileged service user gets root on its own box viassh root@localhost. - Verify positive and negative:
sudo -u claude ssh -n -o BatchMode=yes <host> hostnamefor granted hosts, andPermission deniedfor its own host and every excluded one. Usessh -n; without it a loop of innersshcalls silently swallows the outer script's stdout. - Root on the controller is already root on the fleet through the controller's deploy key, so "controller only" narrows the path, not the blast radius. Say so when presenting the option.
Hosts outside the Ansible inventory (external VPSes)
The baseline-playbook route above only reaches hosts in inventory. For an external box — a VPS
running an agent, holding real credentials — it does not apply, and root is the wrong default.
Settled 2026-09-11 for dfw/hermes:
- Expect root SSH to be refused. A hardened VPS runs
PermitRootLogin no; the give-away isROOT LOGIN REFUSED FROM <ip>in its journal, which means the key matched and policy declined — the key install was fine. Do not "fix" this by loosening a host-wide policy to admit one key. - Two accounts, not one.
claude-admin: sudo-capable, exists only so the RC host can run Ansible there.claude-diag: the narrow one for routine reads — no sudoers grant at all (systemd-journalgroup suppliesjournalctl, so no escalation path exists to widen later),restrict,command="..."inauthorized_keys, and a script that allowlists every argument it turns into a command argument. Say plainly which one is the boundary: it is the script, not the sudoers line. shell: /usr/sbin/nologinkills a forced command. sshd runscommand="..."through the login shell, sonologinyields "This account is currently not available" and a dead account. Use/bin/bashwith a locked password (password: '!');restrict,command=is what prevents a shell, not the shell field. This shipped-broken in rehearsal and was only caught because the playbook was tried against a throwaway host first — do that.- A verification task that only checks
rccan pass vacuously.failed_when: rc != 2went green against a missing script, because an absent file also exits 2. Assert on the refusal message too, and let verification tasks skip under--checkrather than forcing them to run against a copy task that was simulated. - Both accounts carry a
present/absentvar for one-flag revocation, and theclaude-adminplay asserts the key stays out of root'sauthorized_keys. - Point the service user's
~/.ssh/configat the right account per host and backport it into the install playbook — that file is Ansible-managed, so a hand edit is drift.
Related: the ssh-exposure-audit skill (this work surfaced a real exposure on one of the two
hosts; the account was the errand, the finding was the value).
6. Small traps, in the order they bit
-
git ls-remote --exit-code -h <repo> HEADnever matches:-hrestricts torefs/headsand no branch is named HEAD. The reachability probe reported every repo unreachable with working auth. Drop-h. -
ansible.posix.known_hostsreportedchangedevery run with the identical key present; an exact-linelineinfileis idempotent by construction. -
A
systemctl starttyped while still insidesudo -iu claudefails withFailed to start …: Access deniedplus apkttyagentcomplaint — it's the wrong user, not a broken unit. -
ssh -T git@github.comas the service user is the definitive auth check ("Hi !"); trust it over any wrapper's verdict. -
Restore-test coverage for this host should check the binary (
sudo -u claude /home/claude/.local/bin/claude --version), not a unit: a restored clone has no network and the units are Condition-gated. -
The fleet's weekly-sweep exposure arrays (
LOOPBACK_ONLY/LAN_OK) have no entry for a host with no listener at all; that's correct, same as the Ansible controller. -
Pinning GitHub's key from
ssh-keyscanwithstdout_lines[0]breaks trap 2's fix. The first line is sometimes keyscan's# github.com:22 SSH-2.0-<banner>comment, and the banner changes. The task then appended a new comment on most runs (9 found) and never re-ran clean, which would hide a real host-key change. Select thegithub.com ssh-ed25519 …line itself (homelab-ansiblef594983, 2026-10-29). -
A session whose worker has ended stays dead, and the server says nothing. The app shows the session, sends
initialize, and gets no answer, while every other session on the same server works. Checkpsfor--session-id cse_<id>under the server's PID (find the id with the remote-session tools'list_sessions). With stdout nulled (above), the journal records only server startup/crash errors, never workers. Recover with/resumefrom a new session on that server; restarting the unit also works but kills every live session on it. Put the service user insystemd-journal(read-only) so sessions can at least read the server's errors without root. (2026-11-05)
7. Terminal access alongside Remote Control, and herdr
Remote Control has no terminal client — claude --help on 2.1.267 lists no subcommand that
attaches to an RC server. The phone and claude.ai/code drive it; a terminal reaches the same work
by SSHing in and running claude there, over the same ~/.claude (credentials, memory repo,
CLAUDE.md, skills). Two front-ends, one session store.
- Grant the owner's workstation key directly to the service user, not just root
(
claude_rc_owner_pubkey+ apresent/absentswitch inclaude-code-install.yml). It is not a privilege increase where the same key is already on root, and it stops routine work happening as root.ssh <host>then lands with the right PATH, memory and CLAUDE.md with nosudo -iu. - Don't resume the same thread on two surfaces at once. Settle a convention instead — the one that holds here is terminal primary, phone for check-ins and permission prompts.
herdr
herdr (herdr.dev, Apache-2.0) is a tmux-like multiplexer that is agent-aware: every pane is
marked working / blocked / idle, so a session waiting on input is visible without cycling tabs.
- Install it on the host the agents run on, not the laptop. Its value is the background server
that survives a dropped SSH connection (
prefix+qdetaches,herdrreattaches). A local install with panes SSHing out still loses the remote processes on disconnect. - It replaces tmux; it does not layer on it. Both use the
ctrl+bprefix — nesting means double-prefixing every keystroke. - Installer is clean for a no-sudo service user: single static binary to
~/.local/bin, SHA-256 verified against a manifest, touches no shell rc and no system path.HERDR_INSTALL_DIRoverrides the target. - Check the live version, don't trust the README — the GitHub README said 0.4.0 while the
installer shipped 0.9.0, and the two differ substantially (0.9.0 has
--remote, named sessions, and a socket API the older write-ups don't mention). herdr integration install claudemerges into~/.claude/settings.jsonrather than replacing it — existing hooks survive, but diff it anyway. It adds oneSessionStarthook that guards onHERDR_ENV/HERDR_SOCKET_PATH/HERDR_PANE_IDand exits in ~3 ms when absent, so RC sessions driven from the phone are unaffected. Verify that rather than assuming it: a hook onSessionStartfires for every server instance on the box, not just terminal ones.- The integration is optional — herdr detects agent state by screen analysis without it; the hook only adds native session restore.
- Surviving a reboot (2026-09-30/10-01): a client-launched
herdrserver dies with the host.herdr.service(system unit,User=claude,ExecStart=herdr server, inclaude-code-install.yml) brings it back at boot and restores saved panes headless, before any client attaches, each re-runningclaude --resume <id>. Two traps: Claude Code never persists trust for the home directory, so a pane in~stops at the trust prompt on every restore; and herdr saves the cwd a pane was created with, socdinside it changes nothing. Create the workspace withherdr workspace create --cwd ~/projects/<name>. herdr --skillprints a skill file for driving herdr's own panes/agents via its socket API.
Two traps that only appear once someone actually uses the terminal surface
-
~/.local/binis a login-shell-only PATH entry.~/.profileadds it;~/.bashrcdoes not, and is guarded against non-interactive shells anyway. Soclaudeis not found in a herdr/tmux pane (interactive, non-login) and not found undersshRemoteCommand(non-interactive, non-login). Fix with a guarded block in~/.bashrcfor panes, and an absolute path forRemoteCommand. Verify withbash -ic, neverbash -lc— a login shell is the one kind that was never in play, and checking that way certifies nothing. Put the fix in the playbook; a hand-edited~/.bashrcdies at the next rebuild. -
claude --continuewill silently grab the session the Remote Control server is serving. It resumes the most recent session for that directory, and the RC server's sessions live in the same store under the same user. The result is one conversation with two live front-ends — exactly what the coexistence convention exists to prevent. Useclaude --resume, which lists sessions so a human chooses, and reserve--continuefor a surface you know owns the thread. Observed 2026-09-11 within minutes of the terminal surface existing: the terminal resumed the phone's session and printed its own state summary, which read like a person asking a question. -
The terminal's
/resumepicker hides every session started from the app (2026-11-08, Claude Code 2.1.318). Remote Control sessions are written with"entrypoint":"sdk-cli", and the picker leaves those out, so on this host it showed only two empty "(session) · 0 bytes" stubs while dozens of real sessions existed. Resume one by ID instead: find it withgrep -l '"customTitle":"<name>"' ~/.claude/projects/<dir>/*.jsonl, thenclaude --resume <id> --remote-control(the--remote-control [name]flag exists in 2.1.318; untested combined with--resume). From the app,/resume <id>in a new session on the same server works. Related: archiving a session in the app ends its worker (the pane then shows "Remote Control disconnected … (code 4090)"), and herdr keeps restoring whatever session a pane last ran, archived or not.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |