2.5 KiB
2.5 KiB
| type | subtype | title | summary | tags | scope | last_updated | date | last_reviewed | source | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| reference | api-integration | Claude Code /remote-control connection behavior and keep-alive | Why Claude Code Remote Control sessions drop (host suspend, ~25-min server-side WebSocket limit, broken auto-reconnect) and how to keep or resume them. |
|
global | 2026-07-08 | 2026-07-08 | 2026-07-08 | servers/desktop |
Claude Code /remote-control connection behavior
How Remote Control (phone → local CLI session via claude.ai) stays connected, what kills it, and how to recover. Verified against docs + GitHub issues as of Claude Code ~v2.1.203 (2026-07).
Connection model
- WebSocket to an Anthropic relay (
wss://api.anthropic.com/v1/session_ingress/ws/); no inbound ports on the host. - Client sends keep-alive frames every ~5 min.
What kills the connection
| Cause | Behavior |
|---|---|
| Host suspend/sleep | Most common killer. If the host is unreachable >~10 min the session times out and the process exits. Desktop power management counts only local input as activity — remote-driven sessions look idle. |
| Server-side max lifetime | Server force-closes the WebSocket ~every 25 min (code 1006), regardless of keep-alives — GH issue #34868, open. |
| Repeated drops | Auto-reconnect works once (~1s); after ~3 disconnects the session dies permanently with code 1002 — #31853, #34255, open. |
| SIGHUP | Closing the terminal kills the process (tmux prevents this; tmux does NOT survive host suspend). |
| Phone network handoff | WiFi↔cellular switch causes a pong timeout; usually reconnects unless it stacks with the above. |
No CLAUDE_REMOTE_CONTROL_* env vars exist to tune reconnect/backoff as of v2.1.203.
Keeping it alive (Linux host)
systemd-inhibit --what=sleep:idle --why="Claude Code Remote Control" \
tmux new-session -s claude-remote 'claude'
systemd-inhibitblocks idle suspend for the wrapped process's lifetime.- Or disable idle suspend outright (GNOME:
gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type 'nothing'). - Keep the phone app foregrounded; avoid network handoffs mid-session.
Recovery after a drop
- Process still alive: run
/remote-controlagain in the session — manual re-bridge works even when auto-reconnect has given up. - Process dead:
claude --continue(orclaude --session-id <id>) to resume the conversation, then/remote-controlfor a fresh link. - No built-in auto-restart after a permanent (1002) failure.