# vLLM + Ingero bundle image

`ghcr.io/ingero-io/vllm-ingero` is `vllm/vllm-openai` with the Ingero
agent baked in. Use it as a drop-in vLLM OpenAI server that also traces
the GPU work underneath, with no separate agent container.

```
docker run --gpus all --privileged --pid=host -p 8000:8000 \
  -v /var/lib/ingero:/var/lib/ingero \
  ghcr.io/ingero-io/vllm-ingero:latest --model facebook/opt-125m
```

`--privileged --pid=host` let the agent's eBPF uprobes see vLLM's CUDA
and NCCL activity. Read the trace back from the host or an exec:

```
ingero explain --db /var/lib/ingero/vllm.db
ingero query   --db /var/lib/ingero/vllm.db
```

## Degrades safely

If you omit `--privileged`/`--pid=host`, run on a host without BTF, or
otherwise block eBPF attach, the container still serves vLLM normally.
The agent logs one line to `/var/log/ingero-agent.log` and the inference
path is untouched. The agent never blocks or slows vLLM startup.

## When to prefer the two-container compose

For most deployments the side-car compose in the parent directory
(`../docker-compose.yaml`) is cleaner: it keeps vLLM unmodified and runs
the agent next to it. The bundle image exists for the case where one
image is operationally simpler (single artifact to pull, pin, and
schedule). Both share the same agent contract.

## How it is built

`Dockerfile` copies the agent binary out of `ghcr.io/ingero-io/ingero`
(no eBPF rebuild) into a pinned `vllm/vllm-openai` tag. `entrypoint.sh`
backgrounds `ingero trace --record --record-all` then execs the vLLM
OpenAI API server. The `vllm-bundle.yml` workflow rebuilds on agent
release, weekly (new vLLM tags), and on manual dispatch; pull requests
build + smoke-test without pushing.
