Quick Start with Docker

Get CollectorCtrl running locally in under 5 minutes. This is the fastest way to evaluate the platform before committing to a production deployment.

Prerequisites

• Docker installed on your machine (Get Docker)
• Ports 4320 and 4321 available on localhost

Step 1: Run the Management Server

Open a terminal and run:

$docker run -d \\
$  -p 4320:4320 \\
$  -p 4321:4321 \\
$  --name collectorctrl \\
$  --restart unless-stopped \\
$  ghcr.io/collectorctrl/collectorctrl-server:latest

This starts the Management Server with:

• Port 4320 — OpAMP WebSocket gateway for agents
• Port 4321 — Admin UI dashboard and REST API
• SQLite database (zero configuration)

Step 2: Open the Dashboard

Navigate to http://localhost:4321 in your browser.

Default credentials:

• Username: admin
• Password: admin

⚠️ Security note: Change the default password immediately after first login via Profile → Change Password.

Step 3: Install a Supervisor Agent

Now connect an OpenTelemetry Collector to your server. The Supervisor agent runs alongside your collector and manages its lifecycle.

On Linux/macOS (test machine)

First, create a supervisor config file:

$mkdir -p ~/.config/collectorctrl
$cat > ~/.config/collectorctrl/supervisor.yaml << 'EOF'
$server:
$endpoint: 'ws://localhost:4320/v1/opamp'
$tls:
$insecure_skip_verify: true
$capabilities:
$reports_effective_config: true
$reports_own_metrics: true
$reports_own_logs: true
$reports_own_traces: true
$reports_health: true
$accepts_remote_config: true
$reports_remote_config: true
$accepts_restart_command: true
$agent:
$executable: '/usr/local/bin/otelcol'
$passthrough_logs: true
$storage:
$directory: '~/.local/share/collectorctrl/storage'
$telemetry:
$logs:
$level: info
$EOF

Note: Replace /usr/local/bin/otelcol with the actual path to your OpenTelemetry Collector binary.

Then run the Supervisor:

# Download the supervisor for your platform (example: Linux AMD64)
$curl -L -o collectorctrl-supervisor \\
$  https://github.com/CollectorCtrl/CollectorCtrl/releases/latest/download/collectorctrl-supervisor_linux_amd64
$chmod +x collectorctrl-supervisor
$./collectorctrl-supervisor --config ~/.config/collectorctrl/supervisor.yaml

On Windows

1. Download collectorctrl-supervisor_windows_amd64.exe from the releases page
2. Create supervisor.yaml in the same folder:

server:
  endpoint: 'ws://localhost:4320/v1/opamp'
  tls:
    insecure_skip_verify: true

capabilities:
  reports_effective_config: true
  reports_own_metrics: true
  reports_own_logs: true
  reports_own_traces: true
  reports_health: true
  accepts_remote_config: true
  reports_remote_config: true
  accepts_restart_command: true

agent:
  executable: 'C:\Program Files\otelcol\otelcol.exe'
  passthrough_logs: true

storage:
  directory: 'C:\ProgramData\CollectorCtrlSupervisor\storage'

telemetry:
  logs:
    level: info

3. Run: collectorctrl-supervisor_windows_amd64.exe --config supervisor.yaml

Step 4: See Your Agent in the Dashboard

Go back to http://localhost:4321. Within a few seconds, your agent should appear in the Fleet Overview.

You'll see:

• Hostname and OS information
• Health status (Healthy/Unhealthy/Disconnected)
• Current config hash
• Service name and version

Step 5: Create Your First Policy (Optional)

1. Navigate to Fleet → Policies in the sidebar
2. Click New Policy
3. Give it a name like default-config
4. In the Target Selector, use:

   {"matchLabels": {}}
   

   (empty = targets all agents)
5. Paste a basic OpenTelemetry Collector config in the Main Config editor:

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   processors:
     batch:
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [debug]
   

6. Click Publish

The config will be pushed to your agent via OpAMP. The Supervisor will hot-reload it without restarting the collector.

Next Steps

• Install on Windows Server for production
• Install on Linux with systemd for production
• Learn about Fleet Policies
• Read the full documentation

Clean Up

To stop and remove the Docker container:

$docker stop collectorctrl && docker rm collectorctrl