Ultra-lightweight edge-routed remote execution engine.
rexec allows you to execute shell commands on any remote machine (GPU instances, cloud VMs, or containers) directly from your local terminal. Powered by Cloudflare Workers and Durable Objects, it routes traffic through the edge, eliminating the need for public IP addresses, inbound firewall rules, or complex reverse proxy setups.
- Serverless Edge Relay: Built on Cloudflare Workers and Durable Objects, providing global low-latency routing without maintaining self-hosted relays.
- Zero-Dependency Runtimes: Both the remote worker agent and local terminal caller run on standard Node.js without any third-party npm dependencies.
- Three-Tier Architecture:
- Caller (
rexecCLI & universalRexecCallerSDK): Initiates command executions, file transfers, multiplexed PTY sessions, and TCP tunnels using 100% Web standard APIs. - Hub (Cloudflare Worker & Durable Object): Edge routing and streaming relay between callers and worker nodes, featuring zero-parse
client_idpassthrough (TunnelRelay) for interactive PTY and port-forwarding channels. - Agent (
rexec-agent): Remote daemon running on target worker nodes that maintains 4 dedicated persistent WebSocket channels (pty,forward,exec,file) grouped by a process-levelinstance_idto eliminate head-of-line blocking across domains.
- Caller (
- Real-Time Streaming & Process Fidelity: Chunked execution output streamed via dedicated
execWebSocket and Server-Sent Events (SSE). Clean process termination and signal forwarding onCtrl+C(SIGINT). - Multiplexed Interactive PTY:
rexec ttyopens remote pseudoterminals (defaulting to the remote login shell), supports detach/re-attach (Ctrl-]), byte-offset incremental replay on reconnect, and multiplexes all concurrent sessions and management RPCs (list,kill,persist) over a single/ws/ptyconnection. - Full-Duplex Port Forwarding: Multiplexed TCP tunneling over a single shared
/ws/forwardWebSocket (rexec forward [local_port:]remote_port), seamlessly routing local ports to remote web services (Jupyter, Gradio, ComfyUI, TensorBoard) without public IP or inbound firewalls. - Streaming File & Directory Transfers: Bi-directional file and directory transfers over the dedicated
filechannel, powered by WHATWG Web Streams and streamingtarpipelines with real-time transfer progress bars.
flowchart LR
subgraph Client["Caller (CLI / Web / VS Code)"]
Caller["RexecCaller\n(rexec CLI / Web UI / Extension)"]
end
subgraph Edge["Cloudflare Edge Network"]
Hub["RexecHub (Durable Object)\nTunnelRelay · TaskRelay · TransferRelay"]
end
subgraph Remote["Remote Node (GPU VM / Container)"]
Agent["rexec-agent (Node.js)\ninstance_id group"]
PTY["PtyManager\n(RingBuffer & PTYs)"]
Fwd["ForwardManager\n(Local TCP Sockets)"]
Task["TaskManager\n(Subprocesses)"]
FS["TransferManager\n(Files & tar Streams)"]
end
Caller -- "1a. /ws/pty (Multiplexed PTY + RPCs)\n1b. /ws/forward (Multiplexed TCP Tunnels)" <--> Hub
Caller -- "1c. POST /exec (HTTP SSE)\n1d. GET/POST /file/* (Web Streams)" <--> Hub
Hub -- "2a. /ws/agent/pty (client_id passthrough)" <--> Agent
Hub -- "2b. /ws/agent/forward (client_id passthrough)" <--> Agent
Hub -- "2c. /ws/agent/exec" <--> Agent
Hub -- "2d. /ws/agent/file" <--> Agent
Agent <--> PTY
Agent <--> Fwd
Agent <--> Task
Agent <--> FS
Install the rexec command-line tool on your local machine with a single command (requires Node.js 20+):
curl -fsSL https://rexec.edgetool.workers.dev/install/caller | bash(This automatically downloads the standalone client to ~/.local/bin/rexec or /usr/local/bin/rexec and sets executable permissions).
You can connect to the official public Hub directly, or deploy your own relay server to Cloudflare Workers.
-
Public Hub:
https://rexec.edgetool.workers.dev(Ready to use out-of-the-box — no deployment required)
-
Self-Hosted Hub (Cloudflare Workers): Deploy your own isolated relay server with zero configuration:
npm run deploy
No environment variables or secrets are required at deployment time. Static distribution assets (
/install/*,/agent, and standalone bundles) are bundled and deployed automatically.
On your target machine (e.g., remote GPU VM, or container), install and start rexec-agent:
curl -fsSL https://rexec.edgetool.workers.dev/install/agent | bash(This automatically installs the standalone daemon to ~/.local/bin/rexec-agent or /usr/local/bin/rexec-agent).
# Auto-generate a session token on startup
rexec-agent --hub https://rexec.edgetool.workers.dev
# Or specify a custom static token
rexec-agent --hub <hub-url> --token <custom-secret>The agent opens 4 independent WebSocket channels (pty, forward, exec, file) grouped under a single process instance_id. Each channel independently sends link-level pings answered directly by the Hub (pong) and reconnects with the same instance_id if pings go unanswered or the socket sits in CLOSING — replacing only that single channel without disturbing the other 3 channels. Starting a new rexec-agent process with the same token generates a new instance_id and cleanly takes over all 4 channels. GET /health returns both overall agent_connected status and per-channel health (channels: { pty, forward, exec, file }).
Timers are milliseconds. 0 disables that one check. Defaults are in parentheses.
REXEC_HEARTBEAT_INTERVAL_MS— application ping interval (20000)REXEC_HEARTBEAT_TIMEOUT_MS— reconnect if no Hub frame arrives (60000, or 3× the ping interval when only the interval is set)REXEC_RECONNECT_DELAY_MS— wait before the next attempt (3000)REXEC_CONNECT_TIMEOUT_MS— handshake deadline for every attempt (10000)
rexec-agent --help prints the same list.
When started without --token, rexec-agent automatically generates a secure session token and outputs ready-to-use local execution commands:
[rexec-agent] Connected to hub. Node ID: gpu-vm-01
[rexec-agent] Session Token: rexec_sec_e4b1a82f3c4d5e6f7a8b9c0d1e2f3a4b
======================================================
Session Token generated!
To run commands from your local machine, use:
rexec --hub <hub-url> --token rexec_sec_e4b1a82f3c4d5e6f7a8b9c0d1e2f3a4b <command...>
Or set environment variables:
export REXEC_HUB=<hub-url>
export REXEC_TOKEN=rexec_sec_e4b1a82f3c4d5e6f7a8b9c0d1e2f3a4b
======================================================
On your local machine, set your environment variables (e.g., in ~/.bashrc or ~/.zshrc):
export REXEC_HUB=<hub-url>
export REXEC_TOKEN=<your-secret-token>rexec statusExample output:
Hub Status: ok
Node ID: gpu-vm-01
Agent Connected: YES (Online)
Channels: pty=on forward=on exec=on file=on
Active Tasks: 0
# Run remote command (default fallback)
rexec "nvidia-smi"
# Explicit subcommand syntax
rexec run python train.py --epochs 10 --batch-size 32
# Specify a working directory relative to the remote workspace
rexec --cwd backend "pytest tests/"
# Override execution timeout in milliseconds (default: 300000 / 5 minutes)
rexec --timeout 600000 "make build"
# Use shell pipes and complex commands
rexec "cat /proc/cpuinfo | grep 'model name' | head -n 1"
# Escape commands matching subcommands
rexec -- pull origin mainrexec tty opens a remote pseudoterminal (defaulting to the remote user's login shell when no command is given, or executing argv directly) and attaches your local terminal. Keystrokes (including Ctrl-C) and window resizes go directly to the remote process. Press Ctrl-] to detach while leaving the remote session running.
# Open the remote default login shell ($SHELL -l)
rexec tty
# Run an interactive command in a PTY
rexec tty codex
rexec tty bash -lc "htop"
# Open a persistent session (no orphan TTL after detach)
rexec tty --persistent bash
# List, re-attach, toggle persistence, or kill remote PTY sessions
rexec tty list
rexec tty attach <session_id>
rexec tty persist <session_id> on
rexec tty kill <session_id>All concurrent PTY sessions and management RPCs (list, kill, persist) within a caller instance are multiplexed over a single shared /ws/pty connection. If the connection drops, rexec tty automatically reconnects and performs byte-offset incremental replay from the agent's ring buffer without losing output. If another caller attaches to the same session_id, only that specific session is detached (pty:detached) on the previous caller without dropping its WebSocket or affecting its other open terminals.
The first session makes the agent download the platform PTY native module from the Hub (/install/pty/) into ~/.cache/rexec. Linux, macOS, and Windows (x64 and arm64) are supported. /exec is unchanged and still runs one-shot commands without a PTY.
# Download a file from remote agent to local directory
rexec pull loss.png
# Download to a specific local path (or directory)
rexec pull /content/loss.png ./plots/loss.png
# Download an entire directory recursively (streaming tar)
rexec pull -r /content/sample_data ./sample_data
# Overwrite existing local file
rexec pull -f model.pt ./checkpoints/best.pt
# Upload a local file to remote workspace
rexec push config.yaml
# Upload a local directory recursively (streaming tar)
rexec push -r ./my_module /content/my_module
# Upload to a specific remote destination
rexec push ./dataset.zip /content/dataset.zip# Forward remote port 8080 to localhost:8080
rexec forward 8080
# Forward remote port 8000 to localhost:9000 (e.g., Gradio, ComfyUI, TensorBoard, Jupyter)
rexec forward 9000:8000rexec forward multiplexes all port-forwarding rules and concurrent TCP streams over a shared /ws/forward WebSocket (ForwardMuxClient), sending link-level pings every 20 seconds. Each local TCP connection is assigned a caller-generated session_id and routed by the Hub via client_id passthrough (${client_id}:${session_id} on the agent). If the tunnel socket closes or no Hub frame arrives for 60 seconds, the caller closes active local TCP sockets from the broken transport so local clients can dial again over a reconnected WebSocket.
Usage:
rexec [options] <command...> Execute remote command (default fallback)
rexec run [options] <command...> Explicitly execute remote command
rexec forward [options] <port...> Forward local port to remote agent port
rexec tty [options] [command...] Open a remote PTY (default login shell) and attach
rexec tty list List remote PTY sessions
rexec tty attach <session> Attach to a session by id or unique prefix
rexec tty kill <session> Kill a remote PTY session
rexec tty persist <session> on|off Keep a session after detach, or restore orphan TTL
rexec pull [options] <remote> [loc] Download a file or directory from remote agent
rexec push [options] <loc> [remote] Upload a file or directory to remote agent
rexec status [options] Check connection and agent status
rexec -- [options] <command...> Escape command collisions with subcommands
Options:
--hub <url> Hub URL (or via REXEC_HUB env var)
--token <secret> Auth Token (or via REXEC_TOKEN env var)
--cwd <dir> Remote working directory relative to remote workspace
--timeout <ms> Command execution timeout in milliseconds (default: 300000)
-r, --recursive Transfer directories recursively via streaming tar
-f, --force Overwrite local target file when pulling
--persistent Keep a new PTY session after the local client detaches
-h, --help Show this help message
Usage:
rexec-agent [options]
Options:
--hub <url> Hub WebSocket/HTTP URL (or via REXEC_HUB env var)
--token <secret> Auth Token (or via REXEC_TOKEN env var)
--workspace <dir> Base workspace directory (default: current working directory)
--node-id <id> Worker node identifier (default: hostname)
-h, --help Show this help message
# Build standalone distributions (dist/rexec.mjs and dist/rexec-agent.mjs)
npm run build
# Start local black-box debug harness (Hub + Agent logging to .debug/engine/)
npm run debug:serve
# Run automated end-to-end test matrix (in another terminal)
npm run debug:test
# Lint and typecheck
npm run format
npm run check