reoclo shell

reoclo shell <serverIdOrName>

Opens an interactive PTY against a runner-connected server using your active API key. The session terminates when you exit the remote shell or close the connection.

Requirements

• The CLI must be attached to an interactive TTY (both stdin and stdout). If you need a one-shot non-interactive command, use reoclo exec instead.
• The target server must be runner-connected. SSH-only servers are not supported in v1.0.

Authentication

reoclo shell uses your active profile’s API key, sent as a Sec-WebSocket-Protocol value at WebSocket handshake time:

Sec-WebSocket-Protocol: reoclo.api-key.v1.<base64url(KEY)>

The key is never placed in the URL or query string, and most reverse proxies redact this header from access logs by default. Required permission on the key: servers:open_terminal for the target server.

Automation Keys

Interactive shell access is denied by default for Automation Keys (rca_*). Granting it requires explicitly adding the terminal operation to the key’s allowed_operations list when you create it. The rationale: a shell session has no per-keystroke audit trail, so this should be opt-in for the rare CI debugging scenarios that need it.

Examples

Open a shell on a server by name:

reoclo shell prod-web-1

Or by UUID:

reoclo shell 019dc1a8-841f-7102-ac5d-3ee9e9353795

Drop in, run a few commands, exit:

$ reoclo shell prod-web-1
Last login: Fri Apr 25 10:23:11 2026 from gateway
prod-web-1 # docker ps --format '{{.Names}}'
reoclo-acme-api
reoclo-acme-worker
prod-web-1 # exit
$

Idle timeout

Sessions are disconnected after 30 minutes of stdin idle (no client→server bytes). On disconnect the CLI prints [idle timeout] and exits with code 1. Output from the remote does NOT reset the idle timer — only your input does.

Resize

The CLI sends an initial window size on connect and re-sends on every SIGWINCH. Most terminals propagate window changes automatically, so resizing your terminal window mid-session works as expected.

Exit codes

Code	Meaning
0	Remote shell exited cleanly.
1	Connection closed unexpectedly, or idle timeout fired.
2	Not connected to a TTY, or server type doesn’t support shell (SSH-only).
3	Authentication or authorization failure (close codes 4001/4403).
5	Server not found (close 4404).

Related

• reoclo exec — run a one-shot command (no PTY, scriptable)
• reoclo logs tail — stream logs without opening a shell
• reoclo servers — list available servers