Agents

An agent in Ampbase is any process that speaks OpAMP, presents a valid agent key, and connects to a channel's endpoint. In day-to-day use that's the Ampbase supervisor managing one of the supported agents — a telemetry collector, an AI coding agent, or an eBPF security agent — but the protocol surface is open, so any conforming OpAMP client works.

The connection

Agents connect to their channel's endpoint over a WebSocket (preferred) or HTTP polling:

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

The agent authenticates with its agent key on every message and reports its own description: instance ID, version, OS, plus any operator-supplied attributes. Ampbase replies with the configuration the agent should be running, signs it, and tracks heartbeats.

Agent keys

An agent key is a channel-scoped bearer credential. It looks like:

agent_01hxj7k9_8f2c4a7e9b1d3a5f7e2c... (~64 chars total)

The 01hxj7k9 segment is the first 8 characters of the channel ULID — Ampbase uses it for fast routing without a database lookup. The rest is random.

Keys are shown once at creation. Ampbase stores only a SHA-256 hash; if you lose the plaintext, generate a new one. Treat keys like passwords: a single key can register an unbounded number of agents into its channel, so most teams generate one key per fleet rollout and revoke them when retiring infrastructure.

Revocation is immediate. Connected agents are disconnected on the next message; new connections holding the revoked key are rejected.

Supported agent types

The Ampbase supervisor manages these agents out of the box. They fall into three classes: telemetry collectors, AI coding agents, and eBPF security agents. What they do differs completely; how you version, roll out, and roll back their config does not.

Other OpAMP clients can connect too, as long as they present a valid agent key and accept signed config payloads.

AI coding agents

agent.type: coding-agents is a different shape from the collector agents above. There is no single managed process — the supervisor wires up whichever coding-agent runtimes are present (Claude Code, Codex CLI, Cursor, Gemini CLI, VS Code Copilot), points their telemetry at a loopback gateway, and runs an events pipeline that redacts each event by policy before anything leaves the workstation. The channel config is a structured policy document, not agent YAML (see supervisor reference → AI coding-agent policy).

Enrollment is a two-command flow: the admin generates a channel key, and the developer runs

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

which writes supervisor.yaml (agent.type: coding-agents), wires the runtimes at the loopback gateway, and installs + starts the platform-native service (systemd on Linux, launchd on macOS). See Install the supervisor → ampbase enroll for the full flag list, and supervisor reference → CLI subcommands for ampbase status and ampbase events tail, which let a developer see exactly what is collected and what leaves — offline, from local files only, and without sudo.

Local-first by default. Until an admin opts in, the tier is metadata-only and both forwarding gates are off: nothing leaves the device. Redaction tiers are metadata-only, no-content, and full; loosening the policy (e.g. metadata-only → no-content) is gated behind a confirmation in the dashboard.

Codex CLI rides its native managed-configuration layer. The supervisor writes /etc/codex/managed_config.toml, which Codex reads on every run and applies above the developer's own ~/.codex/config.toml — no environment variables or per-user steps, and developers can't accidentally shadow the wiring. Details and edge cases (older Codex releases, macOS MDM profiles, CI installs) in supervisor reference → Codex CLI: managed configuration.

Gemini CLI rides its system-settings layer. The supervisor writes a telemetry block into /etc/gemini-cli/settings.json (the highest-precedence Gemini settings file, above the developer's ~/.gemini/settings.json). The default OTLP/HTTP export reaches the gateway on Gemini >= v0.34.0 (an earlier exporter-path bug, google-gemini/gemini-cli#15581, was fixed there); Gemini's logPrompts default is on, so the policy tier pins it explicitly off outside the full tier. Details in supervisor reference → Gemini CLI: system settings.

VS Code Copilot Chat is cooperative-mode only. The supervisor owns the Copilot Chat extension's github.copilot.chat.otel.* keys in VS Code's user settings.json, wiring its native OTel export at the gateway. VS Code exposes no enterprise-policy surface for those keys, so — per the per-mode scope rule — it is wired only under ampbase enroll --user; an enforced enrollment reports it as cooperative-mode-only rather than writing a user file it couldn't guarantee. Details in supervisor reference → VS Code Copilot Chat.

Cloud coding agents (no supervisor)

Some coding agents have no local process to attach a supervisor to — a cloud agent such as Claude Cowork exports OTLP directly to an org-scoped ingest endpoint. The device-side redaction tiers do not apply on this path: there is no supervisor and therefore no events-pipeline redaction. What leaves a cloud agent is governed only by the exporting agent's own configuration (Cowork includes full prompt text by default) plus any ingest-side policy you apply. If you need the managed, versioned, canaried redaction tiers, the telemetry must pass through a supervisor — which a cloud agent cannot. See Cloud-agent OTLP intake for the full treatment.

eBPF security agents

agent.type: tetragon manages Tetragon, Cilium's eBPF security observability and runtime enforcement agent, on standalone Linux hosts — servers, VMs and bare metal. Kubernetes is not supported yet.

Like the coding-agent type it is a different shape from a collector. The channel config is a daemon-config fragment plus a set of TracingPolicies, authored as a bundle rather than a single config, and a bad one kills processes rather than dropping log lines. That difference is why enforcing versions deploy behind a typed confirmation and a staged rollout rather than an ordinary channel-default assignment.

Ampbase never receives your security events. Tetragon writes them as JSON on the host; what can reach Ampbase, per channel and off by default, is a reduced rollup of per-policy counts and cardinality sketches. Ampbase is not a SIEM, not EDR, and not a threat-detection product.

Tetragon policies is the page for this agent — the blast radius, how policies are authored and validated, what an apply actually costs, the enforcement gate and override, the observe-first graduation path, and how to get the events themselves to your own SIEM.

Per-agent credentials (credential_mode)

By default every agent in a channel authenticates with the shared channel key (credential_mode: shared — today's model, and the default for every channel). A channel can opt into managed mode (a channel setting, not a supervisor config field): agents still enroll with the channel key, but are immediately issued a unique, Vault Transit-signed per-instance credential over OpAMP. Managed mode enables single-agent revocation and zero-touch rotation — revoke one stolen laptop without touching the rest of the fleet.

Managed mode requires the agent to persist a credential across restarts, so it is recommended for long-lived, durable hosts (workstations, VMs, bare metal) and discouraged for ephemeral runtimes. The dashboard states the caveat on the toggle itself:

Managed credentials require durable agent state. Fleets on ephemeral storage should stay on shared keys.

A Kubernetes pod without a persistent volume loses its minted credential on every restart and re-enrolls each time — churn with no benefit over the shared key, which is why the toggle warns against it.

Attributes and feature flag targeting

Anything you put under agent.attributes in supervisor.yaml is available to feature flags as a targeting input:

agent:
  type: otelcol
  binary_path: /usr/local/bin/otelcol
  attributes:
    env: production
    region: us-east-1
    role: edge-collector

Combined with the implicit channel_id and agent_id, that's enough for region-by-region rollouts, canary fleets, or A/B'ing two collector configurations. See Feature flags for the rule syntax.

Build components

Telemetry collectors are built, not just configured: two hosts can run "the OpenTelemetry Collector" and only one of them have the Kafka exporter compiled in. The supervisor enumerates what its managed binary actually contains and reports it, and the agent's page — and its drawer's Components tab — show it on a Components card.

The card leads with what matters and lets you browse the rest:

• The headline — how many components are compiled into this build, how many its config requires, and when the build was last reported.
• Required by this agent's config — the components the config version this agent is running requires, and which version that is. A stock collector build enumerates hundreds of components; this is the handful the config names. For a collector that includes components the config defines without wiring them into a pipeline — the build still has to have them for the config to load.
• Required, not in this build — the opposite finding, called out separately because it's the one that bites. This agent's config requires these and its build doesn't have them. Nothing holds this back for you: the channel default reaches every agent whatever its build can run, so either the build or the config has to change.
• Browse the build — the full inventory, one component kind at a time, with a filter. Kinds are the agent's own (exporter, output, inputs), never renamed.

Agent types with no build-time components — Refinery, Tetragon and AI coding agents — don't show a Components card at all: there is no set of components a build of them could be missing, so there is nothing for the card to report.

A card that isn't showing an inventory says which of two things is true, because they have different remedies:

Not yet reported is a gap in what Ampbase knows, not a finding about the build — it is never counted as evidence that a component is present or absent. For when the inventory is read and what makes it fail, see Supervisor reference, under Component inventory; for what Ampbase does with it during a rollout, see Feature flags, under Build eligibility.

Health states

Each agent reports one of three statuses:

OFFLINE is sticky in the UI for a grace period before agents are listed as gone — restarts and short network blips don't churn the agent list.