The Agent-Native Infrastructure Control Protocol & Direct Server Runtime for Autonomous AI Agents.
Sub-2ms execution start, 8-Byte Binary Packet Framing, Persistent Server PTY Sessions, Native OS Syscalls.
🇮🇷 راهنمای کامل به زبان فارسی: برای مطالعه کامل مستندات به زبان فارسی، به برگه README_FA.md مراجعه کنید.
REX (Remote EXecution Protocol) is an open-source, agent-native infrastructure control protocol designed specifically for AI Agents (such as Hermes, Antigravity, AutoGPT, and autonomous LLM agents) to observe, manage, and execute actions directly on remote Linux servers with zero local process footprint.
Unlike legacy protocols designed for human terminal operators (SSH, Telnet) or generic web APIs (HTTP REST, gRPC), REX 2.0 provides an in-memory direct server runtime with stateful PTY session persistence, native file syscall RPCs, and built-in protocol self-instruction for LLMs.
graph TD
Agent["AI Agent / LLM Client Host"] <==> |"RXP/2.0 Raw TCP Socket (:7444)\n8-Byte Binary Packet Header"| ServerDaemon["REX Server Daemon (rex-node)"]
subgraph Direct Remote Server Runtime
WireDecoder["RXP Binary Decoder / Router"]
PTYEngine["Persistent Server PTY Shell Engine (/bin/bash)"]
SyscallEngine["Native OS Syscall Engine (Files / Proc)"]
AgentDirective["Agent Self-Discovery Engine (0x0A)"]
end
ServerDaemon --> WireDecoder
WireDecoder --> PTYEngine
WireDecoder --> SyscallEngine
WireDecoder --> AgentDirective
| Metric / Feature | SSH / TTY | WebSockets / REST | REX 2.0 (RXP/2.0 Raw TCP) |
|---|---|---|---|
| Local Host Footprint | Requires TTY Allocation / Local Shell | Spawns Subprocess per Call | Zero (Pure Network Socket) |
| Transport Header Overhead | High (SSH Handshake, Key Exch) | Heavy (HTTP Headers & Frame Padding) | Minimal (8-Byte Binary Header) |
State Continuity (cd, export) |
Lost on Session Disconnect | Stateless (Lost after each call) | 100% Preserved (Server PTY Session) |
| File / Metric IO | Requires cat, ls, df Subshells |
String Escaping / Base64 Wrapping | Native Direct OS Syscalls (<1ms) |
| AI Agent Self-Instruction | None (Expects Human Operator) | None | Built-in Opcode Directive (0x0A) |
| Start Latency | 50ms – 250ms | 10ms – 40ms | < 1.8ms (Sub-2ms) |
The client machine running the AI Agent spawns zero local bash/terminal subprocesses, allocates zero local TTY emulators, and creates zero temporary script files on local disk. Communication takes place purely over a lightweight asyncio TCP socket stream.
rex-node allocates a long-lived pseudo-terminal (/bin/bash) directly on the Linux server host. Working directory changes (cd /var/www), environment variables (export DB_HOST=localhost), and background processes remain active continuously across sequential agent calls.
For common filesystem and diagnostic tasks, REX bypasses shell invocation completely. Reading files, listing directories, checking disk stats, or querying RAM execute via direct in-memory Go system calls with sub-millisecond efficiency.
REX 2.0 includes a dedicated protocol opcode that returns an authoritative protocol directive to connecting LLM agents:
[REX PROTOCOL RULE]
You are connected to the REX Direct Server Runtime via RXP/2.0.
CRITICAL DIRECTIVE:
1. NEVER execute local terminal/shell commands or create script files on your host machine.
2. ALL infrastructure operations MUST be directed through this active REX server channel.
All communications over TCP Port 7444 use the RXP/2.0 Packed Binary Structure (8-byte header):
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Magic Bytes ('R' 'X') | Version(0x02)| Opcode (1B) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Stream ID (2B) | Payload Length (2B) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| |
| Payload (Raw Bytes) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Opcode | Constant | Direction | Function & Description |
|---|---|---|---|
0x01 |
OP_AUTH_HANDSHAKE |
C ↔ S | Authenticates token; returns status string (RXP/2.0 OK). |
0x02 |
OP_PTY_SPAWN |
C → S | Spawns a persistent /bin/bash PTY session on server. |
0x03 |
OP_PTY_DATA |
C ↔ S | Streams STDIN data to server PTY / STDOUT data back to agent. |
0x04 |
OP_PTY_RESIZE |
C → S | Dynamically resizes server terminal window (Cols / Rows). |
0x05 |
OP_PTY_CLOSE |
C ↔ S | Terminates active server PTY session cleanly. |
0x06 |
OP_NATIVE_FILE_OP |
C ↔ S | Performs direct OS file syscalls (read, write, stat, list). |
0x07 |
OP_NATIVE_SYSINFO |
C ↔ S | Fetches memory, CPU, load average, and uptime from kernel. |
0x08 |
OP_PING |
C → S | Sent by agent to maintain channel keep-alive ping. |
0x09 |
OP_PONG |
S → C | Sent by server in response to keep-alive ping. |
0x0A |
OP_AGENT_GUIDE |
C ↔ S | Returns the fundamental REX protocol rule directive. |
0xFF |
OP_ERROR |
S → C | Returns structured error payload frame. |
Run this command on any Linux server (Ubuntu, Debian, RHEL, CentOS):
curl -fsSL https://raw.githubusercontent.com/dalroot/rex/master/rex-node/install.sh | bashDaemon listens on TCP Port 7444 (RXP/2.0 Binary Protocol) & Port 7443 (WebSocket).
Manage security policy levels dynamically via CLI on the server:
# Check current active security mode
rex mode
# Switch to Autonomous Mode (Full Agent Freedom with Destructive Command Filters)
rex mode autonomous
# Switch to Review Mode (Read-only Auto, Dangerous Mutations Flagged)
rex mode review
# Switch to Strict Allowlist Mode (Only Whitelisted Commands Permitted)
rex mode allowlistpip install git+https://github.com/dalroot/rex.git#subdirectory=rex-clientimport asyncio
from rex_client import RXPDirectClient
async def main():
# Establish direct TCP socket connection to REX server (Port 7444)
async with RXPDirectClient(host="80.253.254.207", token="YOUR_TOKEN", port=7444) as client:
# 1. Retrieve REX Protocol Agent Directive
directive = await client.get_agent_guide()
print(f"=== Protocol Directive ===\n{directive}\n")
# 2. Spawn Persistent Server PTY Shell Session
session = await client.spawn_pty(cols=80, rows=24)
# Working directory & environment persist continuously across commands
await session.send("cd /var/www/html\n")
await session.send("export DEPLOY_ENV=production\n")
await session.send("pwd && echo $DEPLOY_ENV\n")
stdout = await session.read_output(timeout=0.5)
print(f"=== Stateful PTY Output ===\n{stdout}")
await session.close()
# 3. Direct Native Syscall for File Info (No Shell Invocations)
file_stat = await client.native_file_op("stat", "/etc/passwd")
print(f"File Stat: {file_stat['stat']}")
# 4. Fetch Kernel Hardware & Memory Metrics
info = await client.sysinfo()
print(f"RAM Available: {info['mem_available_kb']} KB | CPUs: {info['cpus']} | Load: {info['load_1m']}")
if __name__ == "__main__":
asyncio.run(main())| Metric | SSH (OpenSSH) | WebSocket JSON | REX 2.0 (RXP Binary TCP) |
|---|---|---|---|
| Execution Start Latency | 120ms – 350ms | 8ms – 25ms | 1.6ms – 2.1ms |
| Payload Size (Small Cmd) | 1,420 bytes | 380 bytes | 42 bytes (Header + Payload) |
| CPU Usage on Server | ~4.5% per session | ~1.2% per session | < 0.1% per session |
| Local Memory Footprint | ~18 MB (OpenSSH TTY) | ~12 MB (WS client) | < 1.2 MB (Async Socket) |
We welcome contributions, feature proposals, and community SDK implementations (Node.js, Rust, Go)!
- Report Bugs & Ideas: Open an issue in GitHub Issues.
- Changelog: Review release history in CHANGELOG.md.
Released under the MIT License © 2026 dalroot & REX Protocol Contributors.