Security

This guide covers comprehensive security best practices for deploying TurboPanel. Securing both the control plane and agents is essential for production deployments. For setup instructions, see Control Plane and Agent Setup.

Introduction

TurboPanel's security model spans the control plane (management interface and API) and agents (remote Docker executors). Both components require attention to authentication, network isolation, and Docker socket access. This guide consolidates security guidelines from both components into a unified reference.

Control Plane Security

TLS/SSL Configuration

# nginx example
server {
    listen 443 ssl;
    server_name turbopanel.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:18282;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Authentication

The control plane implements:

• Token-based authentication for API access
• Agent token authentication for WebSocket connections
• Secure token storage and rotation policies
• Session management for web UI

Network Isolation

• Use Docker networks to isolate containers
• Restrict Docker socket access to necessary containers only
• Implement firewall rules to restrict access to port 18282
• Use VPN or private networks for agent communication when possible
• Consider Docker Swarm or Kubernetes network policies

Docker Socket Security

Mitigation strategies:

• Run control plane in isolated Docker network
• Use Docker socket proxy for read-only access if applicable
• Implement audit logging for Docker operations
• Regularly review and rotate credentials
• Monitor Docker daemon logs for suspicious activity
• Consider Docker context restrictions

Token Management

• Store tokens in environment variables or secrets manager
• Never commit tokens to version control
• Implement token rotation policies
• Use strong, unique tokens for each agent
• Monitor token usage and revoke compromised tokens
• Use secrets management (Docker secrets, Kubernetes secrets, etc.)

Firewall Rules

Recommended:

• Allow inbound to port 18282 only from trusted networks
• Restrict outbound to necessary services only
• Block direct Docker socket access from external networks
• Use fail2ban or similar for brute-force protection
• Implement rate limiting on API endpoints

Non-Root User

The container runs as non-root (turbopanel:turbopanel, UID 9999). The Dockerfile creates this user and switches before running the application.

Agent Security

Authentication

• Agent Token: Use AGENT_TOKEN environment variable for authentication with the control plane
• Token Rotation: Implement token rotation policies in production
• Token Storage: Store tokens securely (secrets manager, environment injection); never in code or image

Network Security

• TLS/SSL: Use HTTPS/WSS for production deployments
• Network Isolation: Run agents in isolated networks when possible (Docker networks, VPC)
• Firewall Rules: Restrict agent port (18284) to control plane only; block unnecessary inbound/outbound

Docker Socket Security

• User Permissions: Agent runs as non-root user (turbopanel:turbopanel, UID 9999)
• Socket Binding: Only bind socket to necessary containers; avoid exposing socket to other services

Best Practices

1. Use strong, unique tokens for each agent
2. Enable TLS/SSL in production
3. Monitor agent connections and activity (logs, metrics)
4. Implement rate limiting on control plane for agent endpoints
5. Regularly rotate authentication tokens
6. Use network policies to restrict agent communication to control plane only

Security Layers Overview

graph TD
    subgraph "External"
        A[Client / Agent] --> B[Network Layer]
    end
    subgraph "Network"
        B --> C[TLS/SSL]
        C --> D[Firewall]
    end
    subgraph "Application"
        D --> E[Authentication]
        E --> F[Token Validation]
        F --> G[Authorization]
    end
    subgraph "Host"
        G --> H[Docker Socket]
    end

Secure Deployment Example

# Control plane behind nginx with TLS
# nginx handles SSL termination and proxies to localhost:18282

# Agent with token from secrets, WSS to control plane
docker run -d \
  --name turbopanel-agent \
  -p 18284:18284 \
  -e AGENT_MODE=websocket \
  -e CONTROL_PLANE_URL=wss://turbopanel.example.com \
  -e AGENT_TOKEN=$(cat /run/secrets/agent_token) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  turbopanel/agent:latest

# Agent connecting to cloud control plane
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=$(cat /run/secrets/agent_token) \
  -v /var/run/docker.sock:/var/run/docker.sock \
  turbopanel/agent:latest

Related Documentation

• Control Plane — Installation and configuration
• Agent Setup — Agent deployment for both modes
• REST API Reference — API structure and authentication