## Description
`headroom proxy --uds PATH` binds an AF_UNIX socket instead of a TCP
port. Request handling is untouched; this is the transport only.
Reasons to prefer it over a loopback port: there's no port to collide
with, nothing listens on the network, and filesystem permissions govern
access. Containers and systemd units can share a socket through a bind
mount or a runtime directory without publishing a port.
Path handling refuses more than it deletes:
- It clears a stale socket left by a crashed proxy.
- It refuses to start when something is still listening on the path,
since two proxies would split traffic.
- It refuses a path that exists as a non-socket, which is far more
likely a mistyped argument pointing at real data than a leftover.
- It refuses a path longer than `sun_path` (108 bytes on Linux, 104 on
macOS/BSD). Otherwise that fails inside `bind()` with an error that
names nothing.
- Missing parent directories are created `0700`. An existing parent's
mode is never changed, and a world-writable, non-sticky parent is
refused.
- On Windows `--uds` is rejected with a clear error.
This PR started as a route to Claude Code Remote Control through
Headroom (#1779). That route was field-tested on Linux and does not
work. `ANTHROPIC_UNIX_SOCKET` passes Remote Control's host check, but
Claude Code then classifies the session as API-key auth, which fails
Remote Control's separate subscription-auth requirement. The
troubleshooting docs record that negative result, and this PR no longer
claims to fix#1779.
Devin's review of this head found two real defects and a few smaller
points; they're listed under "Not tested" below. @Mearman's #3959 fixes
all of them on top of this branch: it is stacked here and carries these
three commits unchanged. #3960 is their standalone alternative.
Maintainers can merge this and then #3959's nine commits, or take #3959
directly.
Refs #1779
## Type of Change
- [x] New feature (non-breaking change that adds functionality)
## Changes Made
- `headroom/proxy/uds.py` (new):
- `prepare_uds_path()`: stale-socket cleanup; refusal of a live
listener, a non-socket path or an over-long path; `0700` for directories
it creates; refusal of an unsafe existing parent
- `remove_uds_path()`
- the `sun_path` limits and the Windows guard
- `socket_usage_lines()`, used by both banners
- `headroom/cli/proxy.py`: the `--uds PATH` option (env `HEADROOM_UDS`)
and the socket banner.
- `headroom/proxy/server.py`: `run_server` prepares the path, passes it
to uvicorn, and removes the socket when it exits. The legacy `python -m
headroom.proxy.server` banner uses the same usage lines.
- `headroom/proxy/models.py`: the `uds` setting on `ProxyConfig`.
- `headroom/settings_store.py`: registers `HEADROOM_UDS`.
- `docs/content/docs/proxy.mdx`: a "Serving on a Unix socket" section.
`docs/content/docs/troubleshooting.mdx` gets the Remote Control finding.
- `tests/test_proxy_uds.py`: 24 tests covering path preparation,
parent-mode handling, `sun_path` limits, the Windows guard, the banners,
and the stale-socket and live-listener cases against real AF_UNIX
sockets.
## Testing
- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
# This head (73f77da2) in a python:3.11-slim container, with the Rust core from the
# headroom-ai 0.36.0 Linux wheel (the branch's version):
== PR #3151 head 73f77da2, Python 3.11.17, Linux
$ pytest tests/test_proxy_uds.py tests/test_proxy_settings_endpoints.py -q
======================== 52 passed, 1 warning in 5.17s =========================
# Same head, the files this PR touches:
$ ruff check <files> && ruff format --check <files> # ruff 0.16.8
All checks passed!
6 files already formatted
$ mypy headroom/proxy/uds.py headroom/cli/proxy.py headroom/proxy/server.py headroom/proxy/models.py headroom/settings_store.py --ignore-missing-imports --follow-imports=silent --platform linux # mypy 1.19.1
Success: no issues found in 5 source files
```
## Real Behavior Proof
- Environment: Linux (Docker `python:3.11-slim` on a WSL2 kernel),
Python 3.11.17, this PR's head `73f77da2`, isolated
`HEADROOM_WORKSPACE_DIR`, no provider credentials.
- Exact command / steps: `headroom proxy --uds
/tmp/hr-uds/run/proxy.sock` with neither parent directory existing. I
queried it over the socket with httpx's UDS transport, checked the
listening TCP ports in `/proc/net/tcp*`, started a second proxy on the
same path, then stopped the first with Ctrl+C. Finally I started it
again and stopped it with SIGTERM.
- Observed result: the proxy serves over the socket, creates owner-only
parents, binds no TCP port, refuses a second proxy, and cleans up on
Ctrl+C. SIGTERM leaves the socket file behind (see "Not tested"):
```text
GET /health over the socket -> {'service': 'headroom-proxy', 'status':
'healthy', 'ready': True}
socket is a unix socket: True | run/ mode: 0o700 | hr-uds/ mode: 0o700
TCP ports in LISTEN inside the container: none
second proxy on the same path -> exit 1 | ['headroom.proxy.uds.UdsError:
Another process is already listening on /tmp/hr-uds/run/proxy.sock. Stop
it, or choose a different --uds path.']
after Ctrl+C (SIGINT): exit 0 | socket file still present: False
after SIGTERM (systemd/docker stop): exit -15 | socket file still
present: True
```
- Not tested: macOS live, Windows live (`--uds` is refused there;
covered by a unit test), real provider traffic over the socket, and
`--workers` greater than 1. Known limitations at this head, all fixed in
#3959:
- SIGTERM leaves the socket file, because uvicorn re-raises the signal
before `run_server`'s cleanup runs. A restart clears the stale socket.
- A stored `HEADROOM_UDS` overrides `--port`, and `headroom wrap` passes
it to the TCP proxy it starts.
- uvicorn creates the socket `0666`. That's harmless under a `0700`
parent, but reachable by every local user if placed directly in `/tmp`.
## Runtime Rollout Safety
- Rollout-managed feature(s): none; `--uds` is an opt-in CLI flag
- Minimum rollout channel: n/a
- Stable/default behavior changed: no. Without `--uds` (or
`HEADROOM_UDS`) the proxy binds TCP exactly as before.
- Kill switch / disable path: don't pass `--uds` and don't set
`HEADROOM_UDS`
- Unsafe override required: no
- Qualification impact: none for the default TCP path
- Rollback path: revert this PR; no stored state or format changes
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)
## Additional Notes
- This replaces the earlier description, which had been saved with
literal backslash-n sequences instead of newlines and was cut off
mid-sentence, so the template check could not read it.
- The "Not tested" limitations are deliberate disclosure rather than
open questions: #3959 has the fixes and tests for each.
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/3151"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->