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

[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

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 image at ghcr.io/ampbase-io/supervisor is a scratch-based, multi-arch image (no shell, no OS layer). Because the supervisor must exec the agent binary, both pieces need to live in the same container or on a mount.

Bind-mount the agent binary

Simplest pattern — works if you already manage the agent installation 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

For immutable deployments, build a thin image that copies the supervisor binary out of the upstream image and lays it on top of the agent's official image:

FROM ghcr.io/ampbase-io/supervisor:v1 AS supervisor
FROM otel/opentelemetry-collector-contrib:0.110.0
COPY --from=supervisor /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.