Connect your first agent¶

By the end of this tutorial you will have:

• issued a bootstrap token for a brand-new agent,
• started an OpenTelemetry Collector that connects to your Ampora server,
• seen the agent appear in the Fleet view with its capabilities and effective config.

Time: ~ 10 minutes.

Prerequisites¶

• An Ampora instance you can log into as an Admin.
• Docker on the host where you will run the agent (or a collector binary if you prefer running it natively).
• The Ampora server's hostname or IP, reachable from the agent host.

1. Issue a bootstrap token¶

In Ampora:

1. Settings → Tokens.
2. Issue token.
3. Set:
4. Label: tutorial-agent-1 (free text — used to identify the token in audit logs).
5. TTL: 24h.
6. Group: leave empty for now; we will move the agent later.
7. Issue.

A modal shows the plaintext token once. Copy it now.

2. Prepare the collector configuration¶

Save the following as agent-config.yaml on the agent host:

extensions:
  opamp:
    server:
      ws:
        endpoint: wss://AMPORA_HOST/v1/opamp
        headers:
          Authorization: "Bearer YOUR_TOKEN_HERE"
    instance_uid: 01J0000000000000000000000A
    capabilities:
      reports_effective_config: true
      reports_remote_config: true
      reports_health: true
      accepts_remote_config: true

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s

exporters:
  debug:
    verbosity: basic

service:
  extensions: [opamp]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

Replace AMPORA_HOST with your hostname (e.g. ampora.example.com) and YOUR_TOKEN_HERE with the token you just copied.

3. Start the collector¶

docker run --rm --name tutorial-agent \
  -v "$(pwd)/agent-config.yaml:/etc/otelcol/config.yaml:ro" \
  -p 4317:4317 -p 4318:4318 \
  otel/opentelemetry-collector-contrib:0.115.1 \
  --config=/etc/otelcol/config.yaml

Watch the agent's stdout. Within a few seconds you should see lines like:

opamp client connecting to wss://...
remote_config received version=...
component health reports enabled

If you see an authentication error, double-check the token and the URL. The OIDC troubleshooting page and the Agents do not connect page cover the common pitfalls.

4. See the agent in Ampora¶

In Ampora, open Fleet. The agent should appear within seconds.

Click into it. You should see:

• Identity — fingerprint, agent type (otelcol-contrib), version, platform.
• Capabilities — the bitfield you set, decoded into named flags.
• Effective config — the YAML you just shipped, byte-for-byte.
• Health — green.
• Last seen — within the last few seconds.

The agent is now under management.

5. Send some data through it¶

Generate a few traces to confirm the pipeline works:

docker run --rm --network host \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
  -e OTEL_SERVICE_NAME=hello-tutorial \
  otel/opentelemetry-go-test:latest

The collector's debug exporter will log the spans. Ampora itself is not the trace backend — it only manages the agent. Swap the debug exporter for otlp and point it at Tempo / Jaeger / Datadog when you want real storage.

6. Move the agent into a group¶

Static groups make rollouts trivial:

1. Groups → New group.
2. Static mode, name it tutorial-static.
3. Click Members → Add agent, pick tutorial-agent-1.
4. Save.

Open the agent details again — the Group field now shows tutorial-static. We will use this group in Run a canary rollout.

What you learned¶

• How a bootstrap token authenticates an agent's first connection.
• How the agent reports EffectiveConfig, Health, and Capabilities.
• How an agent gets onboarded into a static group.

Next¶