Skip to content
Reoclo Reoclo Reoclo Docs

reoclo shell

reoclo shell <serverIdOrName>

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

Requirements

Section titled “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

Section titled “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

Section titled “Automation Keys”

Interactive shell access is denied by default for Automation Keys (rca_*). Granting it requires explicitly adding the server: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

Section titled “Examples”

Open a shell on a server by name:

Terminal window
reoclo shell prod-web-1

Or by UUID:

Terminal window
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

Section titled “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

Section titled “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

Section titled “Exit codes”
CodeMeaning
0Remote shell exited cleanly.
1Connection closed unexpectedly, or idle timeout fired (close 4408).
2Not connected to a TTY, or server type does not support shell (SSH-only).
3Authentication failure: the token is missing, invalid, or expired (close 4001).
4Not permitted: you are signed in but lack access to this server (close 4403).
5Server not found (close 4404).
nAnything else is the remote shell’s own exit code, passed through.

Otherwise the remote shell’s exit code is passed through, so a non-zero exit is usually the command you ran rather than Reoclo.

Section titled “Related”