Agent Setup

The TurboPanel Agent is a lightweight service designed to run on managed servers. It executes commands from the control plane, manages Docker containers, and streams logs and SSH sessions back to the control plane.

Overview

Purpose

• Execute commands from the control plane on remote servers
• Manage Docker containers and services
• Stream logs and metrics to the control plane
• Provide SSH session proxying; report server status and health

Relationship to Control Plane

The agent is a lightweight subset of the backend without frontend dependencies. It runs on managed servers and communicates with the control plane, which coordinates multiple agents.

Architecture

graph TD
    subgraph "Cloud Mode"
        A[Edge<br/>Control Plane] -->|Durable Objects| B[Agent on Server 1]
        A -->|Durable Objects| C[Agent on Server 2]
    end

    subgraph "Self-Hosted Mode"
        D[Self-Hosted Control Plane<br/>+ Integrated Agent] -->|WebSocket| E[Agent on Server 2]
        D -->|WebSocket| F[Agent on Server 3]
        D --> G[Local Docker]
    end

    B --> H[Docker Containers]
    C --> I[Docker Containers]
    E --> J[Docker Containers]
    F --> K[Docker Containers]

Deployment Models

Cloud Mode: Control plane runs on Edge platform; agents connect via Durable Objects.

Self-Hosted Mode: Control plane runs on your server; first server needs no separate agent; additional servers run agent with WebSocket.

Installation

docker pull turbopanel/agent:latest
docker run -d \
  --name turbopanel-agent \
  -p 18284:18284 \
  -e AGENT_MODE=durable-objects \
  -e CONTROL_PLANE_URL=https://your-control-plane.workers.dev \
  -e AGENT_TOKEN=your-secret-token \
  -v /var/run/docker.sock:/var/run/docker.sock \
  turbopanel/agent:latest

# On additional servers only (not on control plane)
docker pull turbopanel/agent:latest
docker run -d \
  --name turbopanel-agent \
  -p 18284:18284 \
  -e AGENT_MODE=websocket \
  -e CONTROL_PLANE_URL=http://your-control-plane:18282 \
  -e AGENT_TOKEN=your-secret-token \
  -v /var/run/docker.sock:/var/run/docker.sock \
  turbopanel/agent:latest

Configuration

Environment Variables

Docker Socket

Required: -v /var/run/docker.sock:/var/run/docker.sock

Communication Patterns

WebSocket (Self-Hosted)

Agent connects to ws://CONTROL_PLANE_URL/agent/connect with token in handshake. Commands flow from control plane to agent; responses and logs flow back. Message types include command, response, log, heartbeat. Automatic reconnection with exponential backoff; heartbeat for connection health.

Durable Objects (Cloud)

Agent connects to a Durable Object via HTTP/WebSocket. Flow: authenticate with control plane → control plane creates/retrieves Durable Object → agent establishes WebSocket → commands routed through Durable Object API.

Common Issues

For detailed troubleshooting, see Deployment Troubleshooting.

Related Documentation

• Control Plane — Control plane setup and configuration
• Security — Security best practices for agents
• Deployment Troubleshooting — Common issues and debugging