Initial Commit

logs/.gitignore

@@ -0,0 +1,8 @@
+# The logs themselves are this machine's, not the project's. The
+# directory, its README and this file are tracked so a fresh clone has
+# somewhere for the containers to write - a bind mount whose source does
+# not exist is created by Docker as a root-owned directory, and then
+# every container fails to write to it.
+*
+!.gitignore
+!README.md

logs/README.md

@@ -0,0 +1,69 @@
+# 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.