Runner Servers

The Reoclo Runner is the agent that connects your servers to Reoclo. Your server connects outbound to Reoclo, so no inbound ports are required.

The Reoclo Runner is a lightweight agent that runs on your server and maintains an outbound WebSocket connection to Reoclo. Commands are relayed through this connection, so no inbound ports are required.

Install via Docker

If your host doesn’t have systemd (Alpine, Void, NixOS without a wrapper, rpm-ostree based systems), or if you prefer running agents as containers, install via the official reoclo/runner Docker image instead. The Docker install supports the same deployment workflows, with optional opt-in privileges for host management operations.

When to Use Runner

The Runner works with any Linux server:

• Servers behind firewalls or NAT
• Cloud VMs, bare metal, or home lab machines
• Private networks with no inbound port requirements
• Any server where you want automatic reconnection on network interruptions

Tip

Runner is the recommended connection type for most setups. It works behind firewalls, requires no inbound ports, and the agent handles reconnection automatically.

How It Works

1. You install the Runner agent on your server using a one-line command
2. The agent connects to Reoclo over an outbound WebSocket (HTTPS)
3. When you trigger a deployment, Reoclo sends commands through the WebSocket
4. The agent executes the commands locally and streams the output back
5. The agent maintains a heartbeat. If the connection drops, it reconnects automatically.

No inbound ports are needed. The agent makes all connections outbound.

Prerequisites

Before adding a Runner server, ensure:

• Linux server with Docker, git, and curl installed
• Outbound HTTPS connectivity to Reoclo (no proxy or firewall blocking outbound HTTPS)
• systemd (for service management)
• Docker permissions: The user running the agent must be able to run Docker commands without sudo. Add the user to the docker group if needed:

  sudo usermod -aG docker $USER

  Log out and back in for the change to take effect.

Step-by-Step Setup

1. Generate an Install Command

1. Navigate to Servers in the Reoclo dashboard
2. Click Add Server
3. Select Runner as the connection type
4. Click Generate Install Command

Reoclo generates a short-lived registration token and displays an install command like this:

curl -sSL https://get.reoclo.com | bash -s -- --token <TOKEN>

Caution

The registration token is single-use and expires after a few minutes. If the install fails, generate a new command.

2. Run the Install Command on Your Server

Copy the install command and run it on your server:

curl -sSL https://get.reoclo.com | bash -s -- --token <TOKEN>

The installer does the following:

1. Downloads the Runner binary
2. Creates a systemd service (reoclo-runner.service)
3. Registers with Reoclo using the one-time token
4. Starts the service automatically

You’ll see output like this:

[Reoclo Runner Installer]
Downloading runner binary...
Installing systemd service...
Registering with Reoclo...
Starting reoclo-runner.service...
✓ Runner installed and connected successfully

3. Verify the Connection

In the Reoclo dashboard, the server should transition to ACTIVE within a few seconds. If it stays in PROVISIONING, check the agent logs (see Monitoring the Runner below).

What the Installer Does

The install script performs these steps:

1. Downloads the Runner binary from Reoclo’s CDN
2. Installs the binary to /usr/local/bin/reoclo-runner
3. Creates a systemd service at /etc/systemd/system/reoclo-runner.service
4. Registers the server with Reoclo using the one-time token
5. Starts the service and enables it to start on boot

The service runs as the current user (the user who ran the install command). Ensure this user has Docker permissions.

Monitoring the Runner

The Runner runs as a systemd service. You can check its status and logs using standard systemd commands.

Check Service Status

systemctl status reoclo-runner

You should see:

● reoclo-runner.service - Reoclo Runner Agent
   Loaded: loaded (/etc/systemd/system/reoclo-runner.service; enabled)
   Active: active (running) since ...

View Logs

journalctl -u reoclo-runner -f

This shows the agent’s logs in real time. You’ll see connection events, heartbeat messages, and command execution output.

Restart the Service

If the agent stops responding, restart it:

sudo systemctl restart reoclo-runner

Stop the Service

To stop the agent (e.g., for maintenance):

sudo systemctl stop reoclo-runner

The server will be marked UNREACHABLE in Reoclo until you start the service again.

Connection Resilience

The Runner is designed to handle network interruptions gracefully:

• Automatic reconnection: If the WebSocket connection drops, the agent reconnects automatically with exponential backoff
• Heartbeat monitoring: The agent sends periodic heartbeats to Reoclo. If the connection is lost, Reoclo marks the server UNREACHABLE
• Auto-recovery: When the agent reconnects, the server automatically transitions back to ACTIVE

No manual intervention is needed for transient network issues.

Uninstalling the Runner

To remove the Runner from your server:

1. Stop the service:

   sudo systemctl stop reoclo-runner
   sudo systemctl disable reoclo-runner

2. Remove the service file:

   sudo rm /etc/systemd/system/reoclo-runner.service
   sudo systemctl daemon-reload

3. Remove the binary:

   sudo rm /usr/local/bin/reoclo-runner

4. In the Reoclo dashboard, decommission or remove the server

Troubleshooting

Runner Won’t Connect

Cause: Outbound HTTPS is blocked, or the token expired.

Fix:

1. Verify outbound HTTPS connectivity:

   curl -I https://api.reoclo.com

   You should see a 200 OK or 301 response. If the connection times out, check your firewall or proxy settings.

2. Check the agent logs:

   journalctl -u reoclo-runner -n 50

   Look for connection errors or token validation failures.

3. If the token expired, generate a new install command in the dashboard and run it again.

Server Shows UNREACHABLE

Cause: The agent is stopped or disconnected.

Fix:

1. Check the service status:

   systemctl status reoclo-runner

2. If the service is stopped, start it:

   sudo systemctl start reoclo-runner

3. If the service is running but the server is still UNREACHABLE, check the logs:

   journalctl -u reoclo-runner -f

   Look for connection errors or authentication failures.

Install Command Fails

Cause: curl isn’t installed, or the download failed.

Fix:

1. Ensure curl is installed:

   sudo apt update
   sudo apt install -y curl

2. Verify internet connectivity:

   curl -I https://get.reoclo.com

3. If the download fails, check your firewall or proxy settings.

Deployment Fails with “docker not found” or “git not found”

Cause: Required tools aren’t installed or aren’t in the PATH.

Fix:

1. Install the missing tools:

   sudo apt update
   sudo apt install -y git docker.io curl

2. Verify they’re in the PATH:

   which git docker curl

3. Restart the Runner service:

   sudo systemctl restart reoclo-runner

Permission Denied (Docker)

Cause: The user running the Runner doesn’t have Docker permissions.

Fix:

1. Add the user to the docker group:

   sudo usermod -aG docker $USER

2. Log out and back in (or restart the server) for the change to take effect

3. Restart the Runner service:

   sudo systemctl restart reoclo-runner

Security Considerations

The Runner agent:

• Makes outbound connections only: No inbound ports are opened
• Uses WebSocket over HTTPS: All communication is encrypted in transit
• Authenticates with a one-time token: The token is used only during registration and is never reused
• Runs as a non-root user: The agent runs as the user who installed it (ensure this user has minimal privileges beyond Docker access)

You remain responsible for:

• Keeping the server’s OS and Docker installation up to date
• Restricting Docker access to trusted users
• Monitoring the agent logs for suspicious activity

Next Steps

• Deploy your first application
• Configure environment variables
• Monitor server uptime