Install the supervisor

The Ampbase supervisor (ampbase) is a small Rust binary that sits next to your agent — a telemetry collector, an AI coding-agent runtime, or Tetragon — speaks OpAMP back to Ampbase, applies configs, and reports health. This page covers the install methods in more depth than the quickstart.

macOS (Homebrew)

On a Mac, install from the tap:

brew install ampbase-io/tap/ampbase

That installs a signed and notarized universal binary covering both Apple Silicon and Intel, so there is no Gatekeeper prompt and nothing to un-quarantine.

Tapping first lets you refer to the formula by name afterwards:

brew tap ampbase-io/tap
brew install ampbase

Which is also the form to use in a Brewfile:

tap 'ampbase-io/tap'
brew 'ampbase'

Prefer the fully-qualified ampbase-io/tap/ampbase in scripts and one-liners: it needs no prior brew tap, and it names exactly which formula to install rather than relying on the bare name resolving to this tap.

Homebrew is not required — install.sh below works on macOS too, which is the right choice for MDM-managed images where Homebrew may be absent. Either way, installing only places the binary; run ampbase enroll to connect the machine to a channel.

Binary (install.sh)

The installer script works on Linux and macOS:

curl -fsSL get.ampbase.io | sh

The script:

• Detects your platform: Linux (x86_64, aarch64) or macOS, which resolves to one universal binary covering both architectures.
• Downloads the matching build and verifies its SHA-256 against the release's published checksum manifest, refusing to install on a mismatch.
• Drops the ampbase binary at /usr/local/bin/ampbase.
• On Linux with systemd, writes /etc/systemd/system/ampbase.service. On macOS it writes no service definition — ampbase enroll installs the launchd job, so the two never disagree about who owns the service.

The script takes no options. It always installs the release your Ampbase deployment currently pins, so an install performed today matches the version your fleet expects. To install a different release, download it directly from https://ampbase.io/releases/<version>/ and verify it against the checksums.txt alongside it.

ampbase enroll

For AI coding-agent channels (agent.type: coding-agents), ampbase enroll collapses config, runtime wiring, and service install into one command — you don't hand-write supervisor.yaml or the systemd unit. Install the binary first (above), then:

sudo ampbase enroll \
  --key agent_… \
  --endpoint https://<org>.ampbase.io/channels/<channel>/v1/opamp

This writes /etc/ampbase/supervisor.yaml with agent.type: coding-agents, wires the requested runtimes (--runtimes claude-code,codex-cli,cursor,gemini-cli; default claude-code) at the loopback gateway, and installs + starts the service. Pass --skip-service to write the files and wire runtimes without installing a service — the right choice when baking an MDM image.

The service it installs is platform-native: a systemd unit on Linux, a launchd job on macOS. On macOS the two modes land in different places, which is what makes the no-sudo path possible:

Use --user when you want per-developer wiring without administrator rights — it writes the developer's own user-scope runtime configs rather than the system-wide admin layer. It is also the only mode that wires VS Code Copilot, which has no admin-layer configuration.

To inspect or stop a launchd job:

launchctl print gui/$(id -u)/io.ampbase.supervisor   # --user
launchctl print system/io.ampbase.supervisor         # sudo
launchctl bootout gui/$(id -u)/io.ampbase.supervisor

Re-running ampbase enroll is the supported way to apply a changed configuration — it removes the existing job and waits for the unload to settle before installing the new one. See the supervisor reference for the full flag list, and ampbase status / ampbase events tail for the developer-transparency commands.

The collector-agent types (otelcol, fluent-bit, …) do not use enroll; configure them with a hand-authored supervisor.yaml and the systemd unit below.

systemd

For long-running deployments, run the supervisor under systemd. Drop this unit at /etc/systemd/system/ampbase.service:

[Unit]
Description=Ampbase OpAMP supervisor
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=325
StartLimitBurst=5

[Service]
Type=simple
User=ampbase
Group=ampbase
ExecStart=/usr/local/bin/ampbase --config /etc/ampbase/supervisor.yaml
Restart=on-failure
RestartSec=5
StateDirectory=ampbase
StateDirectoryMode=0700
# Cap agent memory at 512 MiB; raise to match your fleet's working set.
MemoryMax=512M

[Install]
WantedBy=multi-user.target

Then:

sudo useradd --system --no-create-home ampbase
sudo systemctl enable --now ampbase
sudo systemctl status ampbase
sudo journalctl -u ampbase -f

StartLimitBurst and StartLimitIntervalSec stop a supervisor that keeps failing soon after it starts, for example on a config it cannot load. After 5 starts inside 325 seconds, systemd stops restarting it and marks the unit failed, and the agent shows as offline in the console. sudo systemctl status ampbase reports start-limit-hit, and journalctl -u ampbase shows the error from each attempt. Fix the cause, then clear the limit and start it again:

sudo systemctl reset-failed ampbase
sudo systemctl start ampbase

If the supervisor needs paths your hardening profile would normally block (the agent binary, the agent's config directory), use a drop-in override rather than editing the unit:

sudo systemctl edit ampbase

[Service]
ReadWritePaths=/etc/otelcol
ReadOnlyPaths=/usr/local/bin/otelcol

Docker

The supervisor has to exec the agent, so both need to be in the same container.

Prebuilt images

Each image bundles one agent with the supervisor:

The install wizard's Docker and Kubernetes snippets already use these paths. Run the image with your supervisor.yaml mounted:

docker run -d --name ampbase --restart unless-stopped \
  --network host \
  -v "$(pwd)/supervisor.yaml:/etc/ampbase/supervisor.yaml:ro" \
  -v ampbase-state:/var/lib/opamp-supervisor \
  ghcr.io/ampbase-io/otelcol-contrib:0.162.0

Keep the ampbase-state volume: it holds the agent's identity, so a container recreated from a newer image stays the same agent instead of enrolling as a new one. --network host lets applications on the host send to the agent at localhost; without it, publish the ports your config listens on with -p (4317 and 4318 for the collector's OTLP receivers).

A Fluent Bit config must be in the classic format and its [SERVICE] section must set HTTP_Server On, Health_Check On and Hot_Reload On: the supervisor checks the health endpoint after every change, and reloads the config in place. A Vector config should set api.enabled: true, which is how the supervisor checks Vector's health; without it, the supervisor can only tell that Vector is running.

Each tag names the agent version. 0.162.0 is republished whenever a new supervisor is released; 0.162.0-ampbase0.17.0 names both versions and does not change. Images are multi-arch (amd64, arm64), run as UID 10001, and are signed:

cosign verify ghcr.io/ampbase-io/otelcol-contrib:0.162.0 \
  --certificate-identity-regexp '^https://github.com/ampbase-io/telemetry-agent-images/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Bind-mount the agent binary

For other agents, or an agent already installed on the host, run the supervisor image (ghcr.io/ampbase-io/supervisor, distroless, no shell) and mount the agent installed on the host:

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

Custom image with bundled agent

To build your own, copy the supervisor binary out of its image onto the agent's:

FROM ghcr.io/ampbase-io/supervisor:v0.18.0 AS supervisor
FROM otel/opentelemetry-collector-contrib:0.162.0
COPY --from=supervisor /usr/local/bin/ampbase /usr/local/bin/ampbase
COPY supervisor.yaml /etc/ampbase/supervisor.yaml
ENTRYPOINT ["/usr/local/bin/ampbase", "--config", "/etc/ampbase/supervisor.yaml"]

Kubernetes

Run the supervisor as a sidecar in the same pod as the agent. The supervisor and the agent share the pod's process namespace and a config volume; the supervisor writes the agent's config to the shared volume on each deploy and sends SIGHUP. See the supervisor reference for full supervisor.yaml semantics.

Verifying the install

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

On startup the supervisor logs the resolved config, the OpAMP endpoint it'll connect to, and the agent binary it's managing. Look for opamp_connected within a few seconds.

Upgrading

Re-run the installer or pull a newer image. The supervisor preserves its state directory across upgrades, so in-flight rollouts continue. Downgrades are supported as long as the state directory's schema is compatible with the target version — the changelog calls this out.