docs: browser forwarding from sandboxes to host

[murrayju]

Summary

• Research how dtkav/agent-creds implements browser forwarding from Docker sandboxes to the host
• Design an equivalent approach for Ox using Unix domain sockets with directory bind-mounts
• Document a phased implementation plan (xdg-open forwarding -> OAuth callbacks -> cloud provider)

Context

Agents running inside Ox sandboxes sometimes need to open URLs in the host browser (e.g., OAuth flows, preview links). Today there is no mechanism for this. agent-creds solves this with an xdg-open shim inside the container that communicates with an HTTP server on the host, plus temporary reverse proxies for OAuth callback routing.

Key Design Decisions

• Unix sockets over TCP ports: Avoids port allocation conflicts between multiple ox instances. Each session gets its own socket path.
• Directory bind-mount: Mount ~/.ox/sessions/{id}/ into the container rather than the socket file itself, so the socket can be recreated by any ox process without restarting the container.
• Orphan adoption: Any ox process can detect and adopt orphaned sockets for sessions that outlived their original ox process.
• No tcp-bridge needed: Unlike agent-creds (which uses gVisor), our runc containers support Unix sockets natively across bind-mounts.

See docs/plans/browser-forwarding.md for the full writeup.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Ox Agent seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}