> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install with Docker

> Run the zero-code agent as a container, why it needs host PID access and not privileged mode, and how to preview the exact command before running it.

One agent container per host, observing every other container on it.

<Warning>
  **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.
</Warning>

<Info>
  **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](/get-started/license-keys). These pages write it as
     `$OIQ_LICENSE_KEY`.

  Export both before running anything below:

  ```bash theme={null}
  export OIQ_ENDPOINT="https://app.aiaxoniq.com/otlp"   # or your own
  export OIQ_LICENSE_KEY="oiq_..."
  ```
</Info>

## Check the host first

The kernel belongs to the host, so the requirements apply there — **the base
image of your workloads is irrelevant**. A distroless container and a full
distribution container are equally observable.

```bash theme={null}
./bin/oiq-zerocode-preflight
```

See [Install on Linux](/zero-code/linux#1-check-the-host-first) for how to read
the output, and for the `perf_event_paranoid` setting that must be fixed before
the default profile will collect anything.

## Preview, then run

The key is redacted in the preview output, so this is safe to paste into a
ticket:

```bash theme={null}
OIQ_LICENSE_KEY='oiq_...' ./docker/run.sh --endpoint "$OIQ_ENDPOINT" --dry-run
```

Then run it for real:

```bash theme={null}
OIQ_LICENSE_KEY='oiq_...' ./docker/run.sh --endpoint "$OIQ_ENDPOINT"
```

## The two things most quickstarts get wrong

<Warning>
  **`--pid host` is required, and its absence is silent.**

  Observing processes in *other* containers means sharing the host's PID
  namespace. Without it the agent starts, reports healthy, discovers exactly
  one process — itself — and produces essentially nothing.

  There is no error anywhere. If your service inventory did not grow after
  installing, check this first.
</Warning>

<Note>
  **It is not `--privileged`.** The run script drops `ALL` capabilities and
  adds back exactly the profile's set. A privileged container has effectively
  unrestricted host access, which is not what anyone thinks they agreed to when
  installing an observability agent.

  Verify with `docker inspect` if you want to see it rather than read it.
</Note>

## Choosing a profile

```bash theme={null}
OIQ_LICENSE_KEY='oiq_...' ./docker/run.sh --endpoint "$OIQ_ENDPOINT" --profile A
```

All three profiles are available under Docker — unlike Kubernetes, where the
lowest one cannot be expressed. See
[Capability profiles](/zero-code/profiles).

## Confirm it is working

```bash theme={null}
docker logs -f <container>
```

A running container is not the same as a working agent. Confirm data is
arriving — see [Verification](/zero-code/verification).

## Docker Desktop

<Warning>
  **Docker Desktop on macOS or Windows works, and will mislead you.** Your
  containers run inside a Linux virtual machine, so the agent observes what
  runs *in that VM* — which is your containers, and nothing else on your
  machine.

  It is fine for evaluating the agent. It is a poor basis for a demo, and a
  worse basis for estimating what you will see in production.
</Warning>

## Other runtimes

| Runtime              | Status                                                                                    |
| :------------------- | :---------------------------------------------------------------------------------------- |
| Docker Engine 20.10+ | Validated                                                                                 |
| Podman, rootful      | Expected to work; equivalent for this purpose                                             |
| Podman, rootless     | **Unsupported** — cannot grant the required capabilities                                  |
| gVisor               | **Unsupported** — syscalls are intercepted in userspace, so host eBPF sees nothing inside |
| Firecracker, Kata    | **Unsupported** — each guest has its own kernel                                           |

The full matrix, including managed container platforms, is on
[Compatibility](/zero-code/compatibility).

## Next

<CardGroup cols={3}>
  <Card title="Docker Compose" icon="layer-group" href="/zero-code/docker-compose">
    The same agent as a service in your stack.
  </Card>

  <Card title="Verification" icon="circle-check" href="/zero-code/verification">
    Confirm data is arriving.
  </Card>

  <Card title="Troubleshooting" icon="triangle-exclamation" href="/zero-code/troubleshooting">
    Symptom to cause to fix.
  </Card>
</CardGroup>