Working with Agents

Rexec Agents allow you to connect your own servers, workstations, or cloud VMs to Rexec, giving you secure terminal access through the web interface while maintaining full control over your infrastructure.

What are Agents?

An agent is a lightweight process that runs on your machine and establishes a secure WebSocket connection to Rexec. Once connected, you can:

Access your machine’s terminal through the Rexec web UI
Use your actual hardware resources (not limited by Rexec tiers)
Keep your data on your own infrastructure
Connect multiple machines across different locations
Maintain existing development environments

Agent Limits by Tier

Free Tier

Registered Agents: Not available on free tier
Concurrent Terminals: 0

Upgrade to Pro to connect your own machines.

Pro Tier

Registered Agents: Unlimited registrations
Concurrent Terminals: Unlimited connections
Session Recording: Included
Multi-pane Terminals: Supported

Enterprise Tier

Registered Agents: Unlimited
Concurrent Terminals: Unlimited
Advanced Monitoring: System stats and metrics
Priority Support: Dedicated agent assistance

Installing the Agent

Step 1: Register Your Agent

Navigate to Account → Agents in the Rexec UI
Click Register New Agent
Fill in agent details:
- Name: Descriptive name (e.g., “office-workstation”)
- Description: Optional notes
- Tags: Optional labels for organization
Click Create Agent
Save the API token - it won’t be shown again!

Step 2: Download the Agent Binary

Linux (x64)
macOS (arm64)
Windows (x64)

curl -fsSL https://rexec.sh/install-agent.sh | sh
# Or download directly:
wget https://rexec.sh/downloads/rexec-agent-linux-amd64
chmod +x rexec-agent-linux-amd64
sudo mv rexec-agent-linux-amd64 /usr/local/bin/rexec-agent

curl -fsSL https://rexec.sh/install-agent.sh | sh
# Or download directly:
curl -L https://rexec.sh/downloads/rexec-agent-darwin-arm64 -o rexec-agent
chmod +x rexec-agent
sudo mv rexec-agent /usr/local/bin/

Download from:

https://rexec.sh/downloads/rexec-agent-windows-amd64.exe

Or use PowerShell:

Invoke-WebRequest -Uri "https://rexec.sh/downloads/rexec-agent-windows-amd64.exe" -OutFile "rexec-agent.exe"

Step 3: Connect Your Agent

# Set your agent token
export REXEC_AGENT_TOKEN="rexec_<your-token-here>"

# Start the agent
rexec-agent connect --id <agent-id>

With Configuration File:

# Create config file
cat > ~/.rexec-agent.yaml <<EOF
token: rexec_<your-token-here>
agent_id: <agent-id>
server: wss://rexec.sh
EOF

# Start with config
rexec-agent connect --config ~/.rexec-agent.yaml

Running as a Service

systemd (Linux)

Create /etc/systemd/system/rexec-agent.service:

[Unit]
Description=Rexec Agent
After=network.target

[Service]
Type=simple
User=rexec
Environment="REXEC_AGENT_TOKEN=rexec_your_token_here"
ExecStart=/usr/local/bin/rexec-agent connect --id <agent-id>
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable rexec-agent
sudo systemctl start rexec-agent
sudo systemctl status rexec-agent

launchd (macOS)

Create ~/Library/LaunchAgents/sh.rexec.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>sh.rexec.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/rexec-agent</string>
        <string>connect</string>
        <string>--id</string>
        <string>YOUR_AGENT_ID</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>REXEC_AGENT_TOKEN</key>
        <string>rexec_your_token_here</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/sh.rexec.agent.plist
launchctl start sh.rexec.agent

Using Agents from the Web UI

Connecting to an Agent Terminal

Navigate to the Dashboard
Find your agent in the container list (marked with a server icon)
Agent status indicators:
- 🟢 online - Agent is connected and ready
- ⚫ offline - Agent is not connected
Click Connect to open a terminal session
Your terminal opens with the agent’s shell

Agent Terminal Features

Available:

Real-time terminal access
Multi-pane terminal splits (Pro+)
Session recording (Pro+)
System stats monitoring
MFA protection (if enabled)

Not Available:

Resource limits (uses actual machine resources)
Role-based tool installation (use your own setup)
Shell theme customization (uses machine’s shell)

Split Panes with Agents

Create multiple independent shell sessions on the same agent:

In an agent terminal, click the Split button
Each pane gets its own shell session
Sessions are labeled as main, split-{id}, etc.
All panes share the same file system

API Example:

// Connect to main session
const mainWs = new WebSocket('wss://rexec.sh/api/agents/{agent-id}/terminal?token={token}&id=main');

// Connect to new split pane
const splitWs = new WebSocket('wss://rexec.sh/api/agents/{agent-id}/terminal?token={token}&id=split-pane-1&newSession=true');

Managing Agents

Update Agent Info

curl -X PATCH https://rexec.sh/api/agents/<agent-id> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-server",
    "description": "Main production web server"
  }'

Check Agent Status

curl https://rexec.sh/api/agents/<agent-id>/status \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "status": "online",
  "connected_at": "2026-03-04T10:00:00Z",
  "last_ping": "2026-03-04T10:15:00Z",
  "sessions": 2,
  "os": "linux",
  "arch": "amd64",
  "system_info": {
    "hostname": "prod-server-01",
    "num_cpu": 8,
    "memory": {
      "total": 16777216000
    },
    "disk": {
      "total": 107374182400
    }
  },
  "stats": {
    "cpu_percent": 45.2,
    "memory_used": 8388608000,
    "memory_percent": 50.0,
    "disk_used": 53687091200,
    "disk_percent": 50.0
  }
}

List All Agents

curl https://rexec.sh/api/agents \
  -H "Authorization: Bearer $TOKEN"

Delete an Agent

curl -X DELETE https://rexec.sh/api/agents/<agent-id> \
  -H "Authorization: Bearer $TOKEN"

This removes the agent registration. The running agent process will disconnect.

System Monitoring

Agents automatically report system metrics:

CPU and Memory

CPU Usage: Current CPU utilization percentage
Memory: Used vs. total memory
Load Average: System load (Linux/macOS)

Disk Space

Disk Usage: Used vs. total disk space
Mount Points: All mounted filesystems

Network

Connection Status: Last ping time
WebSocket Health: Auto-reconnect on disconnect

Metrics update every 30 seconds and appear in the Dashboard.

Security Best Practices

Token Management

Never commit tokens to Git - use environment variables
Rotate tokens periodically - regenerate API tokens every 90 days
Use separate tokens per agent - easier to revoke if compromised
Store securely - use systemd secrets or macOS Keychain

Network Security

Use TLS/WSS - Rexec enforces encrypted WebSocket connections
Firewall rules - Allow outbound WSS to rexec.sh:443 only
No inbound ports - Agent initiates connection, no ports to expose
Origin validation - Agent validates server certificates

Access Control

MFA on terminals - Enable MFA for sensitive agents
Session recording - Audit terminal activity (Pro+)
Limited permissions - Run agent as non-root user when possible
Time-based access - Use short-lived tokens for temporary access

Troubleshooting

Agent Won't Connect

Check Network:

# Test WebSocket connectivity
curl -i -N -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  https://rexec.sh/health

Verify Token:

# Test API authentication
curl https://rexec.sh/api/agents \
  -H "Authorization: Bearer rexec_your_token"

Check Logs:

# Run agent in foreground to see logs
rexec-agent connect --id <agent-id> --debug

# systemd logs
sudo journalctl -u rexec-agent -f

Common Issues:

Invalid token: Token was revoked or agent was deleted
Network restrictions: Corporate firewall blocking WSS
Wrong agent ID: Ensure ID matches registration

Agent Shows Offline in UI

The agent is considered offline if no heartbeat is received for 2 minutes.Possible Causes:

Agent process stopped
Network interruption
Server restart (agent will auto-reconnect)

Resolution:

# Check if agent is running
ps aux | grep rexec-agent

# Restart agent
sudo systemctl restart rexec-agent

# Or reconnect manually
rexec-agent connect --id <agent-id>

Terminal Connection Failed

If the UI shows the agent as online but terminal connection fails:

Check agent logs for shell startup errors
Verify shell is installed (bash, zsh, or sh)
Test shell manually on the machine: $SHELL --version
Check permissions - agent user needs shell access

Debug Mode:

REXEC_DEBUG=1 rexec-agent connect --id <agent-id>

Multiple Sessions Interfering

If you open multiple terminals to the same agent:

Main session is shared by default (same shell)
Split panes create independent sessions
Use newSession=true in WebSocket connection to get separate shells

Example:

// Shared session (default)
ws://rexec.sh/api/agents/{id}/terminal?id=tab-1

// New independent session
ws://rexec.sh/api/agents/{id}/terminal?id=tab-2&newSession=true

Advanced Configuration

Custom Server URL

Connect to a self-hosted Rexec instance:

rexec-agent connect \
  --id <agent-id> \
  --server wss://rexec.example.com

Auto-reconnect Settings

# ~/.rexec-agent.yaml
token: rexec_your_token
agent_id: abc123
server: wss://rexec.sh
reconnect:
  enabled: true
  max_retries: -1  # infinite
  initial_delay: 1s
  max_delay: 60s

Proxy Configuration

# Use HTTP proxy for WebSocket connection
export HTTPS_PROXY=http://proxy.company.com:8080
rexec-agent connect --id <agent-id>

API Reference

Register Agent

POST /api/agents
Content-Type: application/json
Authorization: Bearer {token}

{
  "name": "my-server",
  "description": "Production web server",
  "os": "linux",
  "arch": "amd64",
  "shell": "/bin/bash",
  "tags": ["production", "web"]
}

WebSocket Terminal Connection

wss://rexec.sh/api/agents/{agent-id}/terminal
  ?token={auth-token}
  &id={connection-id}
  &newSession={true|false}

Parameters:

token - Your auth JWT or API token
id - Stable connection ID (for reconnects)
newSession - Create new shell session (default: false)

Message Format:

// Client → Server (input)
{
  "type": "input",
  "data": "ls -la\n"
}

// Client → Server (resize)
{
  "type": "resize",
  "cols": 120,
  "rows": 40
}

// Server → Client (output)
{
  "type": "output",
  "data": "total 24\ndrwxr-xr-x..."
}

// Server → Client (stats)
{
  "type": "stats",
  "data": {
    "cpu_percent": 23.5,
    "memory_percent": 45.2
  }
}

Use Cases

Development Workstation

Access your powerful desktop from anywhere:

# On your workstation
rexec-agent connect --id workstation-01

# From laptop browser
# Navigate to rexec.sh → Connect to "workstation-01"
# Full access to local files, GPU, etc.

CI/CD Runners

Debug build agents:

# Install on CI runner
curl -fsSL https://rexec.sh/install-agent.sh | sh
rexec-agent connect --id ci-runner-01 &

# SSH into runner during build
# Access via Rexec web UI

Remote Servers

Alternative to SSH for server management:

# Install on server
apt-get update && apt-get install -y wget
wget https://rexec.sh/downloads/rexec-agent-linux-amd64
chmod +x rexec-agent-linux-amd64
./rexec-agent-linux-amd64 connect --id prod-db-01

# Access from web browser (no SSH keys needed)

IoT/Edge Devices

Manage Raspberry Pi and other edge devices:

# On Raspberry Pi
wget https://rexec.sh/downloads/rexec-agent-linux-arm64
chmod +x rexec-agent-linux-arm64
sudo ./rexec-agent-linux-arm64 connect --id pi-sensor-01

# Monitor and debug from anywhere

Get Started

Core Features

Deployment

User Guides

​Working with Agents

​What are Agents?

​Agent Limits by Tier

​Installing the Agent

​Step 1: Register Your Agent

​Step 2: Download the Agent Binary

​Step 3: Connect Your Agent

​Running as a Service

​systemd (Linux)

​launchd (macOS)

​Using Agents from the Web UI

​Connecting to an Agent Terminal

​Agent Terminal Features

​Split Panes with Agents

​Managing Agents

​Update Agent Info

​Check Agent Status

​List All Agents

​Delete an Agent

​System Monitoring

​CPU and Memory

​Disk Space

​Network

​Security Best Practices

​Troubleshooting

​Advanced Configuration

​Custom Server URL

​Auto-reconnect Settings

​Proxy Configuration

​API Reference

​Register Agent

​WebSocket Terminal Connection

​Use Cases

​Development Workstation

​CI/CD Runners

​Remote Servers

​IoT/Edge Devices

Build docs developers (and LLMs) love