Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/brimblehq/rexec/llms.txt

Use this file to discover all available pages before exploring further.

The Agent API enables remote machines to connect to Rexec as external agents, providing terminal access to any Linux/Unix system via WebSocket.

​
Architecture

Agents communicate with the Rexec server using a bidirectional WebSocket protocol:
  1. Registration: Create an agent record and receive an API token
  2. Connection: Agent connects via WebSocket using the token
  3. Communication: Bidirectional message exchange for terminal I/O
  4. Horizontal Scaling: Multi-instance support via Redis pub/sub

​
Authentication

Agents authenticate using API tokens with the agent scope:
  • JWT Tokens: Short-lived session tokens from web UI
  • API Tokens: Long-lived tokens (format: rexec_*) for agent processes
Tokens can be provided via:
  • Authorization: Bearer <token> header
  • WebSocket subprotocol: Sec-WebSocket-Protocol: rexec.token.<token>
  • Query parameter: ?token=<token>

​
Agent Lifecycle

​
1. Registration

Create an agent record and receive credentials: 
POST /api/agents
Returns agent ID and API token for WebSocket connection.

​
2. Connection

Agent establishes WebSocket connection: 
GET /api/agents/:id/ws
Server tracks agent as “online” and updates heartbeat every 15 seconds.

​
3. Heartbeat

Bidirectional ping/pong keeps connection alive:
  • Server sends PingMessage every 15 seconds
  • Agent must respond with PongMessage
  • 45-second timeout for disconnect detection

​
4. Disconnection

On disconnect (graceful or timeout):
  • Agent marked as “offline” in database
  • Redis location registration removed
  • All active sessions notified

​
Session Management

Agents support multiple concurrent shell sessions:
  • Main Session: Default shared session (ID: "main")
  • Split Sessions: Independent sessions (ID: "split-<uuid>")
Each session has independent:
  • Shell process
  • Terminal state
  • I/O streams

​
System Information

Agents report system metrics: 
{
  "hostname": "prod-server-01",
  "num_cpu": 8,
  "memory": {
    "total": 16000000000,
    "available": 8000000000
  },
  "disk": {
    "total": 500000000000,
    "available": 250000000000
  },
  "region": "us-east-1"
}
Stats are broadcast to:
  • Connected user sessions
  • WebSocket events hub
  • Database (persisted)

​
Plan Limits

Agents are subject to tier-based limits:
PlanMax Registered AgentsConcurrent Terminals
FreeVaries by tierMatches registered
ProVaries by tierMatches registered
Admins are exempt from limits.

​
Error Handling

​
Registration Errors

​
error
string
  • "agent limit reached for your plan" - Exceeded plan limits
  • "agent registration not available for your plan" - Plan doesn’t support agents

​
Connection Errors

​
error
string
  • "invalid token" - Authentication failed
  • "agent not found" - Agent ID doesn’t exist
  • "not authorized" - Agent belongs to different user

​
User Connection Errors

​
error
string
  • "agent not online" - Agent is offline
  • "agent terminal limit reached for your plan" - Too many concurrent connections

​
WebSocket Protocol

See Agent Registration for detailed protocol documentation.

​
Multi-Instance Support

Rexec supports horizontal scaling:
  1. Agent Location: Redis stores which server instance hosts each agent
  2. Cross-Instance Routing: Terminal I/O proxied via Redis pub/sub
  3. Session Tracking: Remote sessions tracked separately from local
User (Instance A) → Redis → Agent (Instance B)

​
Security Features

  • CSWSH Prevention: Origin validation on WebSocket upgrade
  • MFA Locking: Agents can be locked pending MFA verification
  • Token Caching: 5-minute Redis cache for token validation
  • Ownership Verification: All operations verify user ownership

​
Next Steps

Registration

Register agents and establish WebSocket connections

File Operations

Upload and download files from containers

Build docs developers (and LLMs) love

Get started for freeTalk to us