English · 中文 (README.zh-CN.md)
- Getting started
- What it is, and how it differs from cloud-sessions
- Install
- Setup: serve a Remote Control session
- The verbs, with examples
- Attach from another machine
- Control room
- Attach from tmux or cmux
- Stop semantics
- Recording
- Limits
- Security and trust
- Security model
- License
- Contributing
Install with Homebrew (brew install ramene/tap/remote-sessions) or as a Claude Code plugin (claude plugin marketplace add ramene/remote-sessions, then claude plugin install remote-sessions@remote-sessions). Then run /remote-room in Claude Code, or remote-sessions attach <session> --tui in a terminal (both new in 0.3.0). Upgrading from 0.2.x: brew upgrade ramene/tap/remote-sessions, claude plugin marketplace update remote-sessions, claude plugin update remote-sessions@remote-sessions, then /reload-plugins or restart Claude Code. The step-by-step guide, with a picture for each step (install, login, first steps, the control room, tmux and cmux, cloud-sessions), is docs/getting-started.md.
Claude Code has two ways to run a session somewhere other than your terminal:
| cloud-sessions | remote-sessions (this repo) | |
|---|---|---|
| Where the session runs | Anthropic's cloud (claude.ai/code, routines) | Your own machine: a Mac, a Linux box, a VM |
| How it starts | cloud-sessions starts it for a repo | You run claude remote-control --name <n> on that machine |
| Who holds the process | Anthropic | You: it is an ordinary local worker process |
| Find a session | your account's list (list --unofficial), and the sessions tracked here |
the worker processes on a host (list, over ssh -n for another host) |
| Stop | a Stop-button link | one SIGINT to the local worker |
| Starting sessions | yes | no: claude remote-control starts them |
The two mods share the event decoder and the cast renderer (copied, same authors). Anything that only exists in the cloud (starting cloud sessions, Stop-button links, batch collect) stays in cloud-sessions.
Out of scope here: approving permission prompts from outside (impossible by design, see Stop semantics) and any --connect TUI.
Three ways, no Rust needed for the first two.
- Claude Code plugin from GitHub (the program is fetched and checksum-verified on first use):
claude plugin marketplace add ramene/remote-sessions
claude plugin install remote-sessions@remote-sessions- Homebrew:
brew install ramene/tap/remote-sessions - From source (needs a Rust toolchain):
cargo install --path crates/remote-sessions-cli
Requirements: claude (Claude Code CLI) on PATH, and, for list --host, stop --host and cast --host, key-based ssh to the other machine.
The plugin (slash commands /remote-serve, /remote-list, /remote-send, /remote-read, /remote-stop, plus an MCP server) lives in claude-mod/remote-sessions. Its launcher runs, in order: $REMOTE_SESSIONS_BIN; a copy bundled in the plugin; an earlier download in the plugin data folder; a remote-sessions already on PATH; else it downloads remote-sessions-<version>-<macos-universal|linux-x86_64|linux-aarch64>.tar.gz from the GitHub release remote-sessions-v<version> and checks its .sha256 before using it. On failure it prints one plain sentence.
Environment variables:
| variable | used by | meaning |
|---|---|---|
REMOTE_SESSIONS_BIN |
plugin launcher | path of the binary to run |
REMOTE_SESSIONS_TOKEN |
events |
API token; otherwise read from ~/.config/remote-sessions/token (0600), then the Claude Code login (macOS keychain, then ~/.claude/.credentials.json). Inside Claude Code /remote-read needs no token |
CLAUDE_CONFIG_DIR |
events |
Claude Code's config folder; its .credentials.json is read in place of ~/.claude/.credentials.json |
REMOTE_SESSIONS_CLAUDE |
send, serve |
path of the claude binary |
REMOTE_SESSIONS_API |
events |
API base URL: https://api.anthropic.com only (plain http only to a loopback test server) |
REMOTE_SESSIONS_MCP_APPROVE |
mcp |
1 lets the MCP tools remote_approve and remote_deny act; off by default (see Security and trust) |
REMOTE_SESSIONS_RECORDING_HOSTS |
recordings |
comma list of ssh hosts (default localhost: set your own) |
All commands print JSON on stdout. A failure prints {"ok":false,"error":"..."} and exits 1.
Remote Control needs:
- a claude.ai subscription login (
claude remote-controlreports it if missing); ANTHROPIC_BASE_URLunset, or pointing at api.anthropic.com. It refuses when it points at a proxy.DISABLE_GROWTHBOOKandCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICunset.
Check first. serve --check names the one variable that fails and starts nothing:
remote-sessions serve --name box --checkIf your shell exports a proxy, start the server in a clean-environment tmux pane:
tmux new -s rc 'env -u ANTHROPIC_BASE_URL -u DISABLE_GROWTHBOOK -u CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC remote-sessions serve --name box'serve runs the same check, then execs claude remote-control --name box. That command asks for the spawn mode once and prints Connected .... Leave the pane running: the session is now listed in the Claude app and can be driven from any machine that has your login.
Run it inside an isolated VM when you can (see Security model).
Example output below uses placeholder hostnames, ids and times.
Local Remote Control workers are processes whose args contain --sdk-url https://api.anthropic.com/v1/code/sessions/cse_<id>. session_<x> on claude.ai equals cse_<x>. --host runs the same listing over ssh -n.
$ remote-sessions list --host mac-a
{"host":"mac-a","ok":true,"workers":[{"cse_id":"cse_01ExampleAAAAAAAAAAAAAAA","host":"mac-a","pid":12345,"session_id":"session_01ExampleAAAAAAAAAAAAAAA","url":"https://claude.ai/code/session_01ExampleAAAAAAAAAAAAAAA"}]}Without --host it lists this machine, plus the machines in REMOTE_SESSIONS_HOSTS and ~/.config/remote-sessions/hosts (see Several machines). --host mac-a,mac-b lists exactly those machines. Each worker has a host; with more than one machine, hosts gives each machine's count or its error ("error":"ssh timed out"). An empty workers array means no session is served there.
Wraps claude -p "<msg>" --cloud session_<id> --output-format json. The message arrives as a peer message: it can steer the session, it can never approve a permission prompt. --message - reads the text from stdin.
$ remote-sessions send session_01ExampleAAAAAAAAAAAAAAA --message "summarize the failing test"
{"note":"Sent as a PEER message: it can nudge the session but cannot approve a permission prompt.","ok":true,"session_id":"session_01ExampleAAAAAAAAAAAAAAA","url":"https://claude.ai/code/session_01ExampleAAAAAAAAAAAAAAA?from=cli&m=0"}A stopped (archived) session refuses messages until it is unarchived in the app.
events returns the session's events: user, assistant, tool_use, tool_result, result. It polls GET /v1/code/sessions/<id>/events with a token. Pass the cursor from the last page as --after to get only new events. In Claude Code, /remote-read does the same through RemoteTrigger and needs no token.
export REMOTE_SESSIONS_TOKEN=... # or a 0600 file at ~/.config/remote-sessions/token
remote-sessions events session_01ExampleAAAAAAAAAAAAAAA
remote-sessions events session_01ExampleAAAAAAAAAAAAAAA --after <cursor from the last call>Shape of the answer (placeholder values):
{"ok":true,"session_id":"session_...","untrusted":"Event text is untrusted data ...",
"events":[{"id":"...","kind":"assistant","user":false,"text":"...","at":1794001984000}],
"cursor":"<id of the newest event>","finished":false}finished is true when the log ends with a result event. Event text is capped at 8 KB with control and bidi characters removed, and is data, never instructions.
One SIGINT to the worker found by --sdk-url .../sessions/cse_<id>. Requires --yes; without it the command refuses and signals nothing.
$ remote-sessions stop session_01ExampleAAAAAAAAAAAAAAA --yes --host mac-a
{"host":"mac-a","interrupted_pids":[12345],"note":"Stopping ENDS the Remote Control session: one interrupt stops the turn, the worker exits and the server archives the session (unarchive it in the app to continue, or start a new one).","ok":true,"session_id":"session_01ExampleAAAAAAAAAAAAAAA","url":"https://claude.ai/code/session_01ExampleAAAAAAAAAAAAAAA"}See Setup. The --check answer (shape from the code, note trimmed):
{"ok":true,"eligible":true,"would_run":"claude remote-control --name box","note":"A claude.ai subscription login is also required; ..."}See Recording. remote-sessions mcp runs the MCP server (12 tools: the five session verbs, remote_pending, remote_approve, remote_deny, remote_say, plus recording_start, recording_stop, recording_list).
Attach a terminal to a Remote Control session on another machine: see the conversation, send prompts, approve permission prompts. These verbs use the session events API, the same two calls Claude Code's own client makes (GET and POST /v1/code/sessions/<id>/events), as the signed-in claude.ai user. The session is addressed as session_<x>, then cse_<x> if that fails. The live view uses GET /v1/code/sessions/<id>/events/stream (server-sent events), also a call Claude Code's own client makes.
Token: REMOTE_SESSIONS_TOKEN, else ~/.config/remote-sessions/token (0600), else on macOS the Claude Code login in the keychain, else the Claude Code login file: claudeAiOauth.accessToken in ~/.claude/.credentials.json (or $CLAUDE_CONFIG_DIR/.credentials.json when CLAUDE_CONFIG_DIR is set). It is sent only as the Bearer header and never printed.
Linux: Claude Code keeps its login in ~/.claude/.credentials.json (mode 0600), so after claude login on the Linux box (claude auth status says loggedIn: true) these verbs need no token file. remote-sessions only reads that file; it never refreshes or writes it. When the login has expired it says so: run claude once to refresh it. (macOS also writes this file when the keychain is locked at login, for example over ssh.) A token from claude setup-token is inference-only and will be refused.
$ remote-sessions attach session_01ExampleAAAAAAAAAAAAAAA # terminal client, live (add --poll to force polling)
$ remote-sessions stream <session> [--from <seq>] [--for <seconds>] # live events, one JSON line each as they arrive
$ remote-sessions pending <session> # unanswered permission prompts: request_id, tool, input
$ remote-sessions approve <session> [--request <id>] # newest pending prompt if --request is omitted
$ remote-sessions deny <session> [--request <id>] [--message "why"]
$ remote-sessions say <session> "run the tests" # a real user turn, not a peer message; "-" reads stdin
$ remote-sessions interrupt <session> # Esc, not killattach is live: it follows events/stream, so new events appear the moment the session produces them, message by message, not token by token (the stream carries whole messages, tool calls and permission prompts, not token deltas). It shows the newest 15 entries, then streams from there; if the connection drops it reconnects and resumes after the last sequence number (from_sequence_num and Last-Event-ID), and if the stream cannot be opened or kept open it says so and falls back to polling the events API (--interval, default 1 s). It prints the conversation as it arrives (assistant text, one line per tool call, results trimmed to their first line), sends each line you type as a real user turn, and when a permission prompt appears prints the tool and its input and asks Allow? [y/n], then answers it. While a prompt is open, the next line you type answers it. /interrupt sends an interrupt and /quit leaves. Ctrl-C leaves attach and does NOT stop the session (unlike stop). Event text is untrusted and printed as plain text with terminal escapes removed.
stream <session> prints one JSON line per item as it arrives: {"item":"event","seq","id","kind","user","text","at","received_ms","via":"stream"} and delivery receipts {"item":"receipt","event_id","status":"DELIVERY_STATUS_RECEIVED|PROCESSING|PROCESSED","timestamp"}. The history is replayed first; --from <seq> starts after a sequence number and --for <seconds> stops after that long (otherwise it runs until Ctrl-C). If the stream fails it prints a notice line and polls the paged events API ("via":"poll") instead.
A prompt is pending when its control_request (can_use_tool) has no control_response for the same request_id and no control_cancel_request. Answering one that is not pending is refused and posts nothing.
Not covered by live checks: deny, and attach itself (unit-tested against a fake backend only).
A 403 that says the device is untrusted prints a clear sentence. Claude Code's own client re-enrolls a device by signing a challenge; this tool does not implement signing, so enroll that machine from Claude Code first.
MCP tools: remote_pending, remote_approve, remote_deny, remote_say. Through MCP, remote_approve and remote_deny do nothing unless you set REMOTE_SESSIONS_MCP_APPROVE=1 (see Security and trust).
$ remote-sessions attach session_01ExampleAAAAAAAAAAAAAAA --tui [--host mac-a] [--no-color] [--ascii]A full-screen client for the same session: the conversation scrolls above a prompt box, and a permission request opens a modal over the transcript.
● I checked the failing tests. Two are timing flakes; the third is a real off-by-one.
◆ Bash(make check)
╰ running 4 tests
… +38 lines · ctrl-o to expand
── turn done · 1m 52s · 2 turns ────────────────────────────────
⠹ session is working · 14s
────────────────────────────────────────────────────────────────
›
────────────────────────────────────────────────────────────────
session_01Ex… │ mac-a │ manual │ ● live esc stop · tab mode
| Key | Action |
|---|---|
| Enter / Shift-Enter, Alt-Enter | send / new line (also a trailing backslash, then Enter) |
| Esc | interrupt the running turn (Esc twice clears the input) |
| Tab | cycle manual, accept-edits, plan; /mode reaches the others |
| Ctrl-O | fold or unfold all tool results |
| PgUp / PgDn / End | scroll / jump to the newest |
| Ctrl-C | leave; the session keeps running |
In the permission modal: 1 Allow once, 2 Deny (Enter confirms), 3 or Tab Deny with a reason, Esc denies. Messages arrive whole, not word by word, so the spinner only counts seconds. All text from the session is untrusted and drawn as plain text. Without a terminal, --tui falls back to the line-mode attach.
New in 0.3.0. control is one full-screen view over your Remote Control sessions and your cloud sessions. It is open source (MIT), like the rest of this repo.
$ remote-sessions control # this machine, every session of your account, and the Routines
$ remote-sessions control --host mac-a,mac-b # this machine and two more (ssh); see Several machines
$ remote-sessions control --tracked # Cloud: only the sessions tracked on this machine (the view before 0.3.2)
$ remote-sessions control --no-routines # hide the Routines (R shows or hides them in the room)
$ remote-sessions control --no-color --ascii # no color, ASCII glyphs (NO_COLOR works too)
$ remote-sessions control --once --size 100x28 # print one frame and exit (--ansi keeps the colors in a pipe)
$ remote-sessions control --demo # placeholder sessions onlyThe control room. Drawn by the real code (crates/sessions-tui/examples/mock_frames.rs) with placeholder data.
a on a session that waits on a permission prompt: the box asks for y. Drawn by the real code with placeholder data.
Enter drops into the session: attach --tui in the same terminal. Drawn by the real code with placeholder data.
The plain CLI without the control room: list --host, then attach.
| Key | Action |
|---|---|
Up / Down, j / k |
select a row (the arrows walk Remote Control, then Cloud) |
PgUp / PgDn, Home g / End G |
move a page, go to the first or the last row |
| Tab | go to the next panel |
| Enter, or a click on the selected row | open chat: the live, two-way chat with the session (type and press Enter to send, Esc goes back). Remote Control: attach --tui; cloud: in the room. If it cannot open, the room names the command to run yourself (for a cloud session the read-only cloud-sessions watch <id>). |
a / d |
approve / deny the waiting prompt of a Remote Control session, then y to confirm (n or Esc cancels; Enter never answers a prompt) |
s |
send a follow-up to a cloud session (Enter sends, Esc cancels, Ctrl-U clears the line) |
r |
read every panel again now |
R |
show or hide Routines |
q, Esc, Ctrl-C, or a click on x close |
leave the room |
| mouse wheel | scroll the panel under the pointer |
By default (0.3.2) the Cloud panel shows every session of your claude.ai account, with its name, repo, state and age, and the Routines with their newest runs. You do not have to track a session to see it. For this, cloud-sessions must be allowed to use your Claude Code login once (cloud-sessions auth use-claude-login, at a terminal). If the account list cannot be read, the panel shows the sessions tracked on this machine and one line that says why and what to run. A session that is tracked here and is also in the account list is one row, with the account's name. A session without a name shows the short form of its id. --all and --routines are still accepted (they are the default now). REMOTE_SESSIONS_CLOUD_ALL=0 is the same as --tracked, and REMOTE_SESSIONS_ROUTINES=0 the same as --no-routines. 0.3.0 and 0.3.1 showed only the tracked sessions unless you gave --all --routines.
Remote Control is read every 3 s and cloud every 10 s, one call each. Cloud sessions raise no permission prompts, so there is nothing to approve for them. The room never answers, sends or stops anything on its own. The frames above come from cargo run -p sessions-tui --example mock_frames > frames.json, which prints every cell of them (symbol, colors, bold) as JSON.
New in 0.3.2. The room never shows a bare empty panel. On a new machine each panel says what is missing, in one line, with the exact command:
| State | What the panel says |
|---|---|
cloud-sessions is not installed |
Cloud: Cloud sessions need cloud-sessions: brew install ramene/tap/cloud-sessions (or the cloud-sessions Claude Code plugin) |
cloud-sessions is installed, but it may not use your Claude Code login yet |
Cloud: Allow your Claude Code login once: cloud-sessions auth use-claude-login (at a terminal; type yes). Until then: tracked sessions only. The command asks a question; a script or a tool call cannot answer it for you. |
| The login is allowed, but the account list still fails | Cloud: only sessions tracked here: the account list failed (<reason>). Fix: cloud-sessions auth use-claude-login |
| The account has no session yet | Cloud: No cloud sessions yet: start one at claude.ai/code or cloud-sessions start --dir <repo> --prompt <text> |
| No Remote Control session on this machine, and no other machine named | Remote Control: No Remote Control session here. Start one: claude remote-control --name box (or remote-sessions serve --name box), then Other machines: --host a,b or ~/.config/remote-sessions/hosts |
When nothing runs anywhere, the room needs no login to say so. When cloud-sessions can read your account, your account's Remote Control sessions that are connected on other machines are rows in the Remote Control panel, with account in the host column (the account list does not name the machine). You see them without ssh. Drop-in, approve and deny work for them by session id, like for any row. Their state needs your claude.ai login on this machine (else unknown).
New in 0.3.1. The Remote Control panel lists this machine and every other machine you name. It reads them from three places, in this order, and lists each machine once:
control --host mac-a,mac-b(a comma list;--hostcan also be given more than once),- the environment variable
REMOTE_SESSIONS_HOSTS=mac-a,mac-b, - the file
~/.config/remote-sessions/hosts, one ssh host per line:
# ~/.config/remote-sessions/hosts
mac-a
mac-b
vm-1 # the VM
This machine is always listed (labeled with its short host name), directly and not over ssh. Each other machine is listed with the same call as list --host: ssh -n -o BatchMode=yes -o ConnectTimeout=5, one thread per machine, stopped after 8 seconds. It uses your own ssh access (your ssh config and keys) and nothing else: no agent, no server, no login is copied to the other machine. A machine that does not answer gets its own row, for example vm-1 ssh timed out, and the others are listed as usual. With more than one machine, each row has a host column and the panel title counts the sessions of each machine (mac-a 2 | mac-b 0 | vm-1 x). r and the normal refresh list every machine again.
Drop-in (attach --tui), approve, deny, read and say go through the session API by the claude.ai session id, so they work for a session on any machine exactly as for a local one. Only stop needs the machine itself: it sends a signal over ssh, so use remote-sessions stop <session> --yes --host <machine>.
A host name must be an ssh config name or a host name: letters, digits, ., _ and - (user@ is allowed). A name that starts with - (an ssh option such as -oProxyCommand=...), or that has spaces or other characters, is refused before ssh runs. /remote-room uses the same sources; REMOTE_SESSIONS_HOSTS is passed into the tmux split.
attach --tui and control are plain terminal programs, so they run in any pane of tmux or cmux:
$ remote-sessions attach session_01ExampleAAAAAAAAAAAAAAA --tui # in any pane
$ tmux new-window 'remote-sessions attach session_01ExampleAAAAAAAAAAAAAAA --tui'
$ cmux new-split right --command 'remote-sessions control'From Claude Code, the plugin command /remote-room (new in 0.3.0) opens the control room in a split beside the Claude Code pane: with cmux new-split right --command ... inside cmux (its terminals set CMUX_SURFACE_ID and CMUX_WORKSPACE_ID), else with tmux split-window -h inside tmux. Outside both it creates nothing and prints the command to run. In the room, Enter drops into a session in the same pane.
Ctrl-C in attach --tui, or q / Esc in the room, only leaves the view: the session keeps running.
stopsends one SIGINT to the worker process. The turn stops, the worker exits, and the server archives the session. It is not an Esc: the session ENDS. Unarchive it in the Claude app to continue, or start a new one.- That is why
stopneeds--yes. From another machine it also needs ssh to that machine. senddelivers a peer message only: it cannot answer a permission prompt. To answer one from another machine usependingand thenapproveordeny, orattach(it asks Allow? [y/n]); they post the same answer the Claude app posts.
Three layers, each usable alone.
remote-sessions cast <session uuid> [--host <ssh-host>] [--out <file>] [--idle-max <s>] [--mp4 <file>]- Input is the session's local transcript,
~/.claude/projects/*/<uuid>.jsonl, on the host that ran it (overssh -nwith--host; the uuid is validated, 8-4-4-4-12 hex). It needs the transcript uuid, not asession_/cse_id: no mapping exists locally. - Output is asciicast v2. Gaps are capped at
--idle-maxseconds (default 2). Without--outthe file is<uuid>.castin the current folder. Transcripts over 64 MB are refused. Read-only. --mp4 <file>also renders an MP4 withcast2mp4(needsaggandffmpeg). If they are missing the cast is still written and the error says which tool is missing.- Play it with
asciinema play <file>.
$ remote-sessions cast 00000000-0000-4000-8000-000000000001 --host mac-b --out rc.cast
$ asciinema play --speed 4 rc.castA cast is any .cast file under ~/.local/share/tmux-logs/<Y>/<M>/<D>/cast/ on a host. Its id is <host>.<YYYYMMDD>.<file name>; every part is validated, so an id cannot name a path outside those folders.
CLI (ssh to each host):
remote-sessions recordings list
remote-sessions recordings start --kind pane --host mac-b --session <tmux target>
remote-sessions recordings start --kind vm --host mac-b --session <tmux target> # a pane that shows a VM
remote-sessions recordings start --kind cloud --host mac-a --session session_... # runs `cloud-sessions cast` there
remote-sessions recordings start --kind rc --host mac-a --session <session uuid> # runs `remote-sessions cast` there
remote-sessions recordings stop <id> # pane and vm recordingspane and vm recordings are made by tmux-record-cast.sh on the host (a tmux pane recorder that is not shipped in this repo); cloud and rc run the sibling cast verbs on that host.
HTTP API:
remote-sessions recordings serve # 127.0.0.1:3790, token in ~/.config/remote-sessions/recordings.token
remote-sessions recordings serve --bind 127.0.0.1:3790 --token-file ~/.config/remote-sessions/recordings.tokenIt prints one line (address and token file path, never the token). The token is 32 random bytes in hex, in a file with mode 0600, generated if missing; a file with looser modes is refused. Send it as Authorization: Bearer <token> (the browser page also accepts ?token=).
| route | answer |
|---|---|
GET /recordings |
{"recordings":[{id,host,name,date,size,frames,duration}],"errors":[per-host ssh failures]} |
POST /recordings with {"kind":"pane or vm or cloud or rc","host":"...","session":"..."} |
201 {"id":"..."} |
DELETE /recordings/<id> |
stop a pane or vm recording |
GET /recordings/<id>.cast |
the asciicast |
GET /recordings/<id>.mp4 |
H.264 MP4 rendered by cast2mp4, cached in ~/.cache/remote-sessions/recordings/; 501 names the missing tool, 502 if rendering fails |
GET /recordings/<id>.gif |
GIF, same rules |
GET /recordings/<id>/live |
server-sent events: one data: line per cast line, then new ones as the file grows, with keepalives |
GET /play/<id> |
web page with the vendored asciinema-player 3.10.0 (Apache-2.0; license kept in crates/remote-sessions-cli/vendor/asciinema-player/ and served at /play/assets/LICENSE) |
Example session:
TOKEN=$(cat ~/.config/remote-sessions/recordings.token) # read into a variable; do not echo it
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3790/recordings
curl -s -H "Authorization: Bearer $TOKEN" -o demo.mp4 "http://127.0.0.1:3790/recordings/<id>.mp4"
open "http://127.0.0.1:3790/play/<id>?token=$TOKEN"
curl -sN -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:3790/recordings/<id>/live"recording_start {kind, host, session}, recording_stop {id}, recording_list {}. They run the same code as the CLI.
- The session API these verbs use (
/v1/code/sessions/<id>/events,events/stream) is the one Claude Code's own clients use, but Anthropic does not document it. It can change without notice, and remote-sessions may break when it does. readandeventsare paged reads of the events API.streamandattachare live overevents/stream, but message by message, not token by token. The recordings SSE route and the player follow a cast file as it grows, line by line.- Token-by-token streaming exists only for Claude running in VMs you run (where the pane itself is recorded). For a Remote Control session on a host, a recording is built from events or the transcript after the fact, or from the pane if the session runs in a recorded tmux pane.
castneeds the transcript uuid, and the transcript on the host that ran the session.paneandvmrecordings needtmux-record-cast.shon the host; MP4 and GIF needcast2mp4,aggandffmpeg. None of these ships in this repo; the API answers 501 with the missing tool name.- Starting
cloudandrcrecordings through the API is unit-tested for validation only; theDELETEfailure modes are not exercised. recordings servebinds loopback only. Reach it from another machine with an ssh tunnel.- The recording hosts default to
localhost: setREMOTE_SESSIONS_RECORDING_HOSTSfor your own. - Pane
stophides the recorder script's output and reports ok if it found the recording. - macOS only so far; the plugin launcher looks for
$REMOTE_SESSIONS_BINorremote-sessionson PATH.
Your login. remote-sessions does not ask for your login. It does not store your login on a server, and it does not receive it: no server of ours is in the code. To call the session API, it reads the login that is already on your machine, in this order: REMOTE_SESSIONS_TOKEN, the file ~/.config/remote-sessions/token, the Claude Code item in the macOS keychain, then ~/.claude/.credentials.json (or $CLAUDE_CONFIG_DIR/.credentials.json). It sends the token only to https://api.anthropic.com. It refuses all other API addresses, except plain http to a loopback test server, and a test checks this.
The hosts in the code.
api.anthropic.com: the session API. This is the only host that gets your login token.claude.ai: session links only. The tool makes no call to it.github.com: the plugin launcher downloads the release binary and its SHA-256 file one time. It refuses a binary whose checksum does not match. It sends no login.127.0.0.1: the optionalrecordings serve(loopback only).
The tool also starts other programs: claude, cloud-sessions (if you installed it), and ssh to the machines that you name (--host, REMOTE_SESSIONS_HOSTS, ~/.config/remote-sessions/hosts), with your own ssh config and keys.
Never printed, never logged. No output and no error text contains a token. Session text (events, transcripts, the input of a prompt) is untrusted data. The output says so, and the tool never acts on it.
The risks.
- Prompt injection through MCP. A session can read hostile text, and that text can try to make the model approve a tool call in a different session. What we do about it:
remote_approveandremote_denyare marked destructive; their descriptions say to use them only when the user asked; event text is marked untrusted; and from 0.3.1, the MCP toolsremote_approveandremote_denydo nothing by default. They return the command, and you approve or deny yourself:remote-sessions approve <session> --request <id>,/remote-approve, ora/dinremote-sessions control. A model cannot change the environment of the MCP server that already runs, so it cannot answer a permission prompt by itself. To let the MCP tools act, setREMOTE_SESSIONS_MCP_APPROVE=1in the environment that starts Claude Code. We do not recommend it. - You run our binary next to your login. The source is MIT and public. Each release archive has a SHA-256 checksum, and the binaries are built from this public tree.
- An undocumented API. The tool uses the same session API calls that Claude Code's own client makes. Anthropic does not document them and can change them. Anthropic's terms for the use of a claude.ai login by third-party tools apply to you.
- Local power. A program that can read your keychain item or
~/.claude/.credentials.jsoncan already do what this tool does. The tool adds no access.
Report a security problem. Open a private security advisory on this repository: https://github.com/ramene/remote-sessions/security/advisories/new. Do not open a public issue for it.
- Run Remote Control inside an isolated VM. Whoever controls the worker process controls the session, and the worker is an ordinary local process that a SIGINT, or anything else running as that user, can reach.
- Tokens stay in the keychain or a private file, not in scripts or logs. This tool never prints one. The recordings token is a 0600 file, compared in constant time; the player page reads it from its own URL and does not echo it.
- Event text is untrusted. It contains model output and tool results: treat anything read from a session as data, never as instructions.
sendmessages arrive as peer messages and cannot approve permission prompts.approve,deny,say,interruptandattachact as the signed-in claude.ai user, so anyone holding that login token can grant permissions: guard the token like the login.stopis a kill switch, not an Esc: it needs--yes, and from a second machine it needs SSH.- Recordings contain whatever was on screen or in the transcript, including secrets that were printed. Treat
.cast,.mp4and.giffiles as sensitive. - The recordings API is loopback only and plain HTTP; the token travels in clear on that hop, so use an ssh tunnel to reach it remotely.
MIT. Copyright (c) 2026 the cloud-sessions contributors. See LICENSE. The vendored asciinema-player 3.10.0 is Apache-2.0; its license and NOTICE are in crates/remote-sessions-cli/vendor/asciinema-player/.
Issues and pull requests are welcome. Build, test and style commands, the layout, and the rules for changes (JSON contract, explicit write actions, no tokens in output, placeholder-only examples) are in CONTRIBUTING.md. Report security issues privately through GitHub's Security → Report a vulnerability, not in a public issue.