53 lines
2.5 KiB
Markdown
53 lines
2.5 KiB
Markdown
---
|
|
type: reference
|
|
subtype: api-integration
|
|
title: Claude Code /remote-control connection behavior and keep-alive
|
|
summary: 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.
|
|
tags:
|
|
- type/reference
|
|
- tool/claude-code
|
|
- domain/devops
|
|
scope: global
|
|
last_updated: 2026-07-08
|
|
date: 2026-07-08
|
|
last_reviewed: 2026-07-08
|
|
source: 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)
|
|
|
|
```bash
|
|
systemd-inhibit --what=sleep:idle --why="Claude Code Remote Control" \
|
|
tmux new-session -s claude-remote 'claude'
|
|
```
|
|
- `systemd-inhibit` blocks 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-control` again in the session — manual re-bridge works even when auto-reconnect has given up.
|
|
- Process dead: `claude --continue` (or `claude --session-id <id>`) to resume the conversation, then `/remote-control` for a fresh link.
|
|
- No built-in auto-restart after a permanent (1002) failure.
|