Skip to content
CyberVyPublic

About

Ultra-lightweight edge-routed remote execution engine

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

118 Commits

Folders and files

Repository files navigation

rexec

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.


Features

  • 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 (rexec CLI & universal RexecCaller SDK): 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_id passthrough (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-level instance_id to eliminate head-of-line blocking across domains.
  • Real-Time Streaming & Process Fidelity: Chunked execution output streamed via dedicated exec WebSocket and Server-Sent Events (SSE). Clean process termination and signal forwarding on Ctrl+C (SIGINT).
  • Multiplexed Interactive PTY: rexec tty opens 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/pty connection.
  • Full-Duplex Port Forwarding: Multiplexed TCP tunneling over a single shared /ws/forward WebSocket (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 file channel, powered by WHATWG Web Streams and streaming tar pipelines with real-time transfer progress bars.

Architecture

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
Loading

Getting Started

1. Install Local CLI (rexec)

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).


2. Setup the Hub (optional)

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.


3. Start the Remote Agent (rexec-agent)

On your target machine (e.g., remote GPU VM, or container), install and start rexec-agent:

Install 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).

Run the Daemon

# 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
======================================================

4. Run Remote Commands (rexec)

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>

Check Connection Status

rexec status

Example 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

Execute Commands

# 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 main

Interactive Terminal

rexec 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.

Transfer Files and Directories

# 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

Port Forwarding (WebUI & TCP Tunnels)

# 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:8000

rexec 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.


CLI Reference

Local Invoker Client: rexec

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

Remote Worker Agent: rexec-agent

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

Development & Testing

# 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

License

MIT

About

Ultra-lightweight edge-routed remote execution engine

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages