Bring Your Own Server (BYOS) Agent

Turn any Linux server into a managed Rexec terminal with the lightweight agent.

What is BYOS Agent?

The Rexec Agent lets you connect your own infrastructure — whether it’s AWS EC2, DigitalOcean droplets, Raspberry Pi, or on-premise servers — to your Rexec dashboard. Access them through the same interface as cloud terminals.

Why Use BYOS?

Use Existing Servers

Leverage servers you already have instead of spinning up new containers.

Access Anywhere

Connect to your production servers from any browser without VPN or SSH keys.

Unified Dashboard

Manage cloud terminals and your own servers in one place.

Team Access

Share server access with team members using collaboration features.

How It Works

Install the lightweight Rexec agent on your server
Register the agent with your Rexec account via API token
Connect through the Rexec dashboard like any other terminal

The agent uses WebSocket connections outbound to Rexec servers. No inbound firewall rules needed.

Installing the Agent

Quick Install (Linux)

# Download and install the agent
curl -fsSL https://rexec.sh/install-agent.sh | bash

# Or install manually:
wget https://github.com/brimblehq/rexec/releases/latest/download/rexec-agent-linux-amd64
chmod +x rexec-agent-linux-amd64
sudo mv rexec-agent-linux-amd64 /usr/local/bin/rexec-agent

Supported Platforms

Platform	Architecture	Status
Linux	amd64 (x86_64)	✅ Stable
Linux	arm64 (aarch64)	✅ Stable
Linux	armv7	⚠️ Beta
macOS	amd64, arm64	✅ Stable
Windows	amd64	🚧 Coming Soon

Registering Your Server

Step 1: Get API Token

Go to Settings → API Tokens in Rexec dashboard
Click “New API Token”
Name: agent-myserver
Scopes: Select agent
Copy the token (starts with rexec_...)

Save your API token securely. It won’t be shown again after creation.

Step 2: Register Agent

# Set your API token
export REXEC_TOKEN="rexec_..."

# Register the agent
rexec-agent register \
  --name "production-web-01" \
  --token "$REXEC_TOKEN" \
  --server https://api.rexec.io

# With optional metadata
rexec-agent register \
  --name "production-web-01" \
  --description "Production web server (us-east-1)" \
  --tags "production,web,us-east-1" \
  --token "$REXEC_TOKEN"

Step 3: Start the Agent

# Run in foreground (testing)
rexec-agent start

# Run as systemd service (recommended)
sudo rexec-agent install
sudo systemctl start rexec-agent
sudo systemctl enable rexec-agent  # Start on boot

# Check status
sudo systemctl status rexec-agent

Configuration

Config File Location

# Linux
/etc/rexec/agent.yaml

# macOS
~/Library/Application Support/rexec/agent.yaml

# Or specify custom location
rexec-agent start --config /path/to/config.yaml

Example Configuration

# /etc/rexec/agent.yaml
agent:
  # Agent ID (auto-generated during registration)
  id: "agent_abc123..."
  
  # Display name in dashboard
  name: "production-web-01"
  
  # Optional description
  description: "Production web server in us-east-1"
  
  # Optional tags for organization
  tags:
    - production
    - web
    - us-east-1

server:
  # Rexec API endpoint
  url: "https://api.rexec.io"
  
  # WebSocket endpoint (usually auto-configured)
  ws_url: "wss://api.rexec.io/ws/agent"

auth:
  # API token for authentication
  token: "rexec_..."

shell:
  # Default shell for sessions
  path: "/bin/bash"
  
  # Support tmux (if installed)
  enable_tmux: true

# Optional: system info reporting
reporting:
  # Report CPU, memory, disk stats
  enable_stats: true
  
  # Stats reporting interval
  interval: 30s

# Optional: logging
logging:
  level: info  # debug, info, warn, error
  file: /var/log/rexec-agent.log

Agent Limits by Tier

Tier	Registered Agents	Concurrent Connections
Free	0	0
Pro	Up to 5	Up to 5
Enterprise	Unlimited	Unlimited

Agent support requires Pro or Enterprise tier. Free tier users can only use cloud terminals.

Connecting to Your Agent

Once registered and online, your agent appears in the dashboard:

Look for servers with 🖥️ icon (vs container icon for cloud terminals)
Click “Connect” to open a terminal session
Use exactly like any cloud terminal

Connection Indicators

Green dot - Agent online and ready
Gray dot - Agent offline
Yellow dot - Agent connected but unresponsive

Managing Agents

List Registered Agents

From the dashboard:

Go to Settings → Agents
View all registered agents with status
See last connected time, OS, architecture

Update Agent Information

# Update name or description
rexec-agent update \
  --name "new-name" \
  --description "Updated description"

# Update tags
rexec-agent update --tags "prod,web,new-tag"

Unregister Agent

# From the server
rexec-agent unregister

# Or from dashboard
# Settings → Agents → [Select agent] → Delete

Unregistering an agent removes it from your dashboard. You’ll need to re-register to use it again.

System Requirements

Minimum

OS: Linux kernel 3.10+ (Ubuntu 18.04+, Debian 10+, CentOS 7+, etc.)
CPU: 1 core
RAM: 256MB free
Disk: 50MB for agent binary
Network: Outbound HTTPS/WSS access

Network & Firewall

Required Outbound Access

# Rexec API (HTTPS)
https://api.rexec.io:443

# WebSocket (WSS)
wss://api.rexec.io:443/ws/agent

The agent initiates all connections outbound. No inbound firewall rules or port forwarding needed.

Proxy Support

# agent.yaml
network:
  proxy:
    http: http://proxy.example.com:8080
    https: http://proxy.example.com:8080
    no_proxy: localhost,127.0.0.1

Security Considerations

Authentication

Agent uses API tokens with agent scope only
Tokens are stored securely on disk (0600 permissions)
WebSocket connections use TLS 1.3

Permissions

The agent runs as:

Non-root user by default (user you ran install as)
Only needs access to shell execution
Does not require sudo/root for terminal sessions

For systemd service installation, brief sudo access is needed. After that, the agent runs as its own user.

MFA Protection

Enable MFA on agents from dashboard:

Go to agent settings
Enable “Require MFA for connections”
Users must authenticate with MFA before connecting

Monitoring & Troubleshooting

Check Agent Status

# Systemd
sudo systemctl status rexec-agent
sudo journalctl -u rexec-agent -f

# Manual logs
tail -f /var/log/rexec-agent.log

Common Issues

Agent shows offline in dashboard

Causes:

Agent not running (systemctl status rexec-agent)
Network connectivity issues
Firewall blocking outbound HTTPS/WSS
Invalid or expired API token

Fix:

# Restart agent
sudo systemctl restart rexec-agent

# Check logs for errors
sudo journalctl -u rexec-agent -n 50

# Test connectivity
curl -v https://api.rexec.io/health

Connection timeout when trying to connect

Causes:

Agent is offline
High network latency
Agent overloaded (too many concurrent sessions)

Fix:

Check agent status in dashboard
Reduce concurrent sessions
Check server resources (CPU, memory)

Permission denied errors in terminal

Causes:

Agent user lacks file/command permissions
Shell not properly configured

Fix:

# Check which user agent runs as
ps aux | grep rexec-agent

# Grant necessary permissions
sudo usermod -aG docker rexec-agent  # if Docker access needed

Advanced Configuration

Custom Shell

shell:
  path: "/bin/zsh"  # Use zsh instead of bash
  args: ["-l"]      # Login shell

Resource Monitoring

reporting:
  enable_stats: true
  interval: 30s
  
  # What to report
  metrics:
    - cpu
    - memory
    - disk
    - network  # Network usage

High Availability

For mission-critical servers:

connection:
  # Reconnect settings
  retry_interval: 10s
  max_retries: 0  # Infinite retries
  
  # Keep-alive
  ping_interval: 30s
  ping_timeout: 10s

Use Cases

Production Server Access

Access production servers without VPN. Enable MFA for security.

Remote Raspberry Pi

Manage home lab or IoT devices from anywhere.

Development Workstations

Connect to your powerful desktop from a laptop or tablet.

Customer Support

Grant temporary access to customer servers for troubleshooting.

Best Practices

Security

Use dedicated API tokens per agent
Enable MFA for production servers
Regularly rotate API tokens (Settings → API Tokens)
Monitor agent connections in audit logs

Organization

Use descriptive names: prod-web-01, dev-db-us-east
Tag agents by environment: production, staging, dev
Tag by location: us-east-1, eu-west-1, on-prem

Reliability

Run agent as systemd service for auto-restart
Enable stats reporting to monitor agent health
Set up log rotation for /var/log/rexec-agent.log

Cloud Terminals

Use cloud-based disposable terminals

Collaboration

Share agent terminals with team members

SSH Access

Connect to agents via SSH gateway

Session Recording

Record sessions on agent terminals

Get Started

Core Features

Deployment

User Guides

​What is BYOS Agent?

​Why Use BYOS?

Use Existing Servers

Access Anywhere

Unified Dashboard

Team Access

​How It Works

​Installing the Agent

​Quick Install (Linux)

​Supported Platforms

​Registering Your Server

​Step 1: Get API Token

​Step 2: Register Agent

​Step 3: Start the Agent

​Configuration

​Config File Location

​Example Configuration

​Agent Limits by Tier

​Connecting to Your Agent

​Connection Indicators

​Managing Agents

​List Registered Agents

​Update Agent Information

​Unregister Agent

​System Requirements

​Minimum

​Recommended

​Network & Firewall

​Required Outbound Access

​Proxy Support

​Security Considerations

​Authentication

​Permissions

​MFA Protection

​Monitoring & Troubleshooting

​Check Agent Status

​Common Issues

​Advanced Configuration

​Custom Shell

​Resource Monitoring

​High Availability

​Use Cases

Production Server Access

Remote Raspberry Pi

Development Workstations

Customer Support

​Best Practices

Security

Organization

Reliability

​Related Features

Cloud Terminals

Collaboration

SSH Access

Session Recording

Build docs developers (and LLMs) love

What is BYOS Agent?

Why Use BYOS?

How It Works

Installing the Agent

Quick Install (Linux)

Supported Platforms

Registering Your Server

Step 1: Get API Token

Step 2: Register Agent

Step 3: Start the Agent

Configuration

Config File Location

Example Configuration

Agent Limits by Tier

Connecting to Your Agent

Connection Indicators

Managing Agents

List Registered Agents

Update Agent Information

Unregister Agent

System Requirements

Minimum

Recommended

Network & Firewall

Required Outbound Access

Proxy Support

Security Considerations

Authentication

Permissions

MFA Protection

Monitoring & Troubleshooting

Check Agent Status

Common Issues

Advanced Configuration

Custom Shell

Resource Monitoring

High Availability

Use Cases

Best Practices

Related Features