Skip to main content
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