# Logs

One file per component, all in this directory. It is bind-mounted into every container in
the stack as `/logs`, so each service writes its own file here rather than leaving you to
work out which `docker compose logs` invocation you wanted.

| File | Component | What is in it |
|---|---|---|
| `api.log` | `owuitools-api` | Every tool call, its outcome, and any error. The first place to look. |
| `gateway.access.log` | `owuitools-gw` | Every request Open WebUI made, with status and duration |
| `gateway.error.log` | `owuitools-gw` | nginx's own problems — upstream timeouts, refused connections |
| `egress.access.log` | `owuitools-egress` | **The audit trail**: every outbound request, allowed or denied. `TCP_DENIED/403` is the private-address guard working, not a fault. |
| `egress.cache.log` | `owuitools-egress` | squid's own startup and errors |
| `searxng.log` | `owuitools-searxng` | Search engine failures, which is what thin results usually are |
| `valkey.log` | `owuitools-valkey` | The cache |
| `octave.log` | `owuitools-octave` | Each sandboxed run, its exit status and duration |
| `netguard.log` | `owuitools-netguard` | The filter's rules as applied, re-verified at startup |
| `vmguard.log` | `owuitools-vmguard` | The same, for the VM sub-agent's namespace |
| `vmgw.access.log` | `owuitools-vmgw` | The sub-agent's calls to Ollama |
| `vmgw.error.log` | `owuitools-vmgw` | |

Everything here is also on the container's stdout, so `docker compose logs -f api` still
works and nothing is hidden from Docker.

## The VM sub-agent is not here, and that is deliberate

`owuivmd` is a systemd service on the host, not a container in this stack. It logs to the
journal, where a system service belongs and where it is still readable when this directory's
filesystem is the thing that broke:

```sh
sudo journalctl -u owuivmd -f
```

Pointing it at this directory would tie a host daemon to wherever the repository happens to
sit, which is one `mv` away from a unit that will not start.

## The VM sub-agent's session transcripts are not here either

They are not logs, they are records of what an agent did, and they outlive the machine:

```sh
sudo vmctl logs            # every session, newest first
sudo vmctl log             # the most recent one, rendered
```

They live in `/var/lib/owuivm/sessions`. Read those, not the journal, when the question is
"what did the agent actually do" — see
[../docs/vm-agent/troubleshooting.md](../docs/vm-agent/troubleshooting.md).

## The verifier's own files

`verify.log` and `verify-error-<tool>.log` are written by `./verify.py` rather than by a
container, and they are overwritten on each run. See [../docs/verifying.md](../docs/verifying.md).

## Rotation

There is none, deliberately: a log that rotates itself is one that has quietly thrown away
the thing you came to look for. They are small — the busiest is `egress.access.log` at
roughly one line per outbound request. If you want rotation, `logrotate` on this directory
is the ordinary answer.

Delete anything here at any time; every component recreates its file on the next write.

## Permissions

The directory is world-writable, because the containers run as several different unprivileged
uids (the API as 10001, squid as 13, valkey as 999) and none of them share a group. It holds
only logs, it is inside your own project directory, and nothing reads from it.