Quickstart

Get an agent connected to Ampbase in about 10 minutes.

By the end you'll have:

• An Ampbase account, organization, and channel
• An agent key tied to that channel
• The Ampbase supervisor running alongside your agent
• A live agent showing up in the web UI

This walkthrough uses OpenTelemetry Collector (otelcol) as the managed agent. The same steps apply to Fluent Bit, Vector, Telegraf, and Refinery — see Agents for the differences.

Onboarding AI coding agents? Claude Code, Codex CLI, and Cursor use a different, shorter path: a single sudo ampbase enroll --key … --endpoint … after installing the binary, governed by a redaction policy rather than agent YAML. Skip to AI coding agents.

1. Sign in and create an organization

Head to ampbase.io and click Sign in. Ampbase uses single sign-on (Google or GitHub), so there is no separate account to create.

Once you land on your dashboard, create an organization. You'll pick an org slug — this becomes part of the OpAMP endpoint URL your agents connect to:

wss://{org_slug}.ampbase.io/channels/{channel_slug}/v1/opamp

Pick something short and stable. The slug can't be changed after creation.

2. Create a channel

Inside the org, create a channel. A channel is the unit of agent grouping: every agent connects to exactly one channel, and configs and feature flags scope to a channel.

Like the org, the channel takes a slug. Model one channel per role — the job its agents do and where their telemetry goes (e.g. clickhouse, vault) — not per environment. Environment, region, and canary are agent attributes you route with feature flags, not separate channels. See Structuring your channels for the full reasoning.

3. Generate an agent key

From the channel's Agent keys page, give the key a label (e.g. production-fleet) and click Create key. You'll be shown a key that looks like:

agent_01hxj7k9_8f2c4a7e9b1d3...

Copy it now — Ampbase only shows the secret once. Treat it like a password: anything holding this key can register agents into your channel.

4. Configure the supervisor

The Ampbase supervisor is a lightweight process that sits next to your existing agent. It talks OpAMP to Ampbase, applies the configs you push from the UI, and reports the agent's health back.

Create supervisor.yaml:

version: 1

server:
  endpoint: wss://acme.ampbase.io/channels/clickhouse/v1/opamp
  api_key: agent_01hxj7k9_8f2c4a7e9b1d3...
  transport: websocket

agent:
  type: otelcol
  binary_path: /usr/local/bin/otelcol
  config_path: /etc/otelcol/config.yaml
  health_check_url: http://localhost:13133/

Replace acme and clickhouse with your org and channel slugs, and api_key with the value from step 3. Point binary_path at your installed agent binary. The full schema is documented in the supervisor reference.

5. Run the supervisor

Pick the install method that matches your environment.

Binary

Run the installer:

curl -fsSL get.ampbase.io | sh

This drops the ampbase binary at /usr/local/bin/ampbase. Then place your config and start it:

sudo mkdir -p /etc/ampbase
sudo mv supervisor.yaml /etc/ampbase/supervisor.yaml
sudo chmod 0600 /etc/ampbase/supervisor.yaml

ampbase --config /etc/ampbase/supervisor.yaml

For a production deployment under systemd, see Install the supervisor.

Docker

The supervisor needs to launch the agent binary, so the simplest container pattern bind-mounts both your supervisor.yaml and the agent binary into the supervisor image:

docker run --rm \
  --network host \
  -v $(pwd)/supervisor.yaml:/etc/ampbase/supervisor.yaml:ro \
  -v /usr/local/bin/otelcol:/usr/local/bin/otelcol:ro \
  -v /etc/otelcol/config.yaml:/etc/otelcol/config.yaml \
  ghcr.io/ampbase-io/supervisor:latest

For a bundled image that ships both the supervisor and the agent in one container, see Install the supervisor.

6. Watch the agent connect

Within a few seconds you should see your agent in the channel's Agents page, reported as HEALTHY once it passes its first health check.

If nothing shows up after 30 seconds:

• Confirm the supervisor logs show a successful WebSocket handshake. The endpoint URL and api_key are the usual culprits.
• Confirm the agent binary path is correct and executable by the supervisor user.
• Check that outbound wss://*.ampbase.io:443 is reachable from the host.

What's next

You have a live agent. The natural next steps:

• Your first config — push a managed config from Ampbase and watch the agent reload.
• Feature flags — route different agents to different config versions for safe rollouts.
• Agents — how agent connections, keys, and supported agent types work.