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, tested and visible in the product, and it is not yet self-service: there is no in-product installer and no download. Ask your account contact for the distribution.Once it is running, find it under Zero-code in the dashboard — the hosts reporting, the services each discovered, the agent version on every node, and how recently each was last heard from. Its telemetry is ordinary OTLP and needs nothing special: it also appears in Services, Traces and Metrics exactly like SDK telemetry. 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 → API 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.
--offline is the air-gapped path. It installs from a tarball you already have instead of downloading one, and it still verifies the checksum — the verification is the point of the installer, not the download.

​
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

To go back to the previous version rather than remove the agent entirely:
It restores the generation that was installed before the last upgrade — the binary, the configuration and the systemd unit together, because rolling back the binary while leaving a newer unit in place would run the old agent at the new privilege level. There is exactly one rollback target, and rolling back consumes it. The snapshot is taken when an install replaces another install, so a first install has nothing to roll back to, and a second --rollback in a row has nothing left. To move forward again, re-run the installer. 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.