Skip to main content
The agent runs as one systemd service per host, observing every process on it.
Availability. The zero-code agent is an early-access distribution. It is installable, upgradable and tested, and it is not yet an integrated part of the product: there is no dashboard page for it, no in-product installer and no self-service download. Ask your account contact for access.Its telemetry, once flowing, is ordinary OTLP and needs nothing special — it appears in Services, Traces and Metrics exactly like SDK telemetry does. That is the design rather than a shortcut.
Before you start, you need two values.
  1. Your base endpoint — shown on Get Started in the dashboard. These pages write it as $OIQ_ENDPOINT.
  2. A license key — created in Settings → License Keys, starting oiq_. Requires the Admin role. See Create a license key. These pages write it as $OIQ_LICENSE_KEY.
Export both before running anything below:
Give the endpoint as a base URL — not a signal path. The tooling refuses .../v1/traces outright rather than letting it fail later as a confusing 404 at ingest.

​
1. Check the host first

1

Run preflight

It reads only. It installs nothing, sends nothing, and loads no eBPF program — it is safe to run on production.
2

Read the result

A host that passes looks like this:
A ⚠ never blocks; a ✗ always does. The capability warning describes your current shell, and the installer grants capabilities through setcap and systemd. Do not chase it.The one you must not override is this, on the same host, for the default profile:
The agent would start, hold every capability, pass its own checks, report healthy and collect nothing at all. Fix it on the host:
Preflight also emits machine-readable output for a CI gate — the human report goes to stderr, so this composes cleanly:

​
2. Preview, then install

--dry-run prints exactly what would happen and changes nothing. When you are satisfied:
sudo -E is not optional. It preserves OIQ_LICENSE_KEY across the privilege change. Without it the installer writes a placeholder and tells you so — the agent then installs cleanly and every export is rejected with 401.The key is read from the environment rather than passed as a flag so that it does not land in your shell history or in ps output.

​
What the installer does

1

Runs preflight

Skippable with --skip-preflight, which you should not use.
2

Downloads the upstream agent and verifies its SHA-256

Against the checksums shipped with the distribution. A mismatch is fatal and there is no skip flag.
3

Installs the binary and applies the capability profile

Using setcap, plus the systemd unit’s ambient capabilities.
4

Generates the configuration and the credential file

Configuration at mode 0644; endpoint and key at mode 0600.
5

Writes and starts the service

​
What lands on disk

​
Options

See Capability profiles before changing --profile.

​
3. Confirm it is running

Then confirm data is actually arriving — a running agent is not the same as a working one. See Verification.

​
Upgrading

Re-run the installer. Upgrades happen in place and preserve your configuration: config.yaml and agent.env are kept unless you pass --force-config. An installer that silently discarded tuned route patterns on upgrade would be a defect.
The systemd unit is always regenerated, because it encodes the capability profile. A stale unit would leave the agent running at the old privilege level while you believed you had changed it — which is the failure you would least want to be silent.Run the audit tool after any upgrade to confirm the privilege you actually have.

​
Removing

Nothing is left in the kernel either way — eBPF programs are released when the process exits. No reboot, no module to unload.

​
If something is wrong

Capability enforcement is doing its job — the agent refuses to attach partially and then report nothing. The message names exactly what is missing.The usual cause is setcap failing on a filesystem without extended attribute support. systemd’s ambient capabilities still grant them, so check the unit is the thing actually starting the process.
In order of likelihood: perf_event_paranoid above 1, then a rejected license key showing as 401 in the log. Both, with the commands to confirm each, are on Troubleshooting.
Route unification is on by default, but your own explicit route patterns always beat the heuristic. See Troubleshooting.

​
Next

Verification

Confirm data is arriving, and rule out the silent failure.

Capability profiles

What --profile actually changes.

Troubleshooting

Symptom to cause to fix.