feat(proxy): serve on a Unix domain socket (--uds)

`headroom proxy --uds PATH` binds an AF_UNIX socket instead of a TCP port.
Request handling is untouched; this is the transport shell only.

The motivation is the client-side gate in #1779. Claude Code v2.1.196+ parses
ANTHROPIC_BASE_URL and compares the host against api.anthropic.com exactly,
disabling Remote Control, the 1M window, and on-demand tool loading whenever a
loopback proxy is configured. The gate is also satisfied by
ANTHROPIC_UNIX_SOCKET, so a socket transport lets a client keep a first-party
base URL while its traffic still reaches Headroom. Headroom cannot fix this
server-side the way --1m restores the context-1m header, because both the
eligibility check and the Remote Control bridge live in the client.

The socket is useful on its own terms too: no port to collide with, nothing
listening on the network, and access governed by filesystem permissions.

Path handling refuses more than it deletes. It clears a stale socket left by a
crashed proxy, but refuses to start when something is still listening (two
proxies would split traffic), when the path exists as a non-socket (far more
likely a typo'd argument over real data than a leftover), or when the path
exceeds the platform's sun_path limit, which otherwise fails inside bind()
with an error that names nothing. The parent directory is created 0700, which
is the whole access-control boundary since a Unix socket carries no
credentials of its own.

POSIX only: Windows exposes no socket.AF_UNIX to Python and asyncio has no
Windows UDS transport, so the CLI rejects --uds up front and points at --port.

Docs cover the flag, the permission model, and the Claude Code wiring, with
the Remote Control route marked experimental and unverified end-to-end.

Refs #1779

Author: Ayushraj06-bit

docs/content/docs/proxy.mdx

@@ -32,6 +32,7 @@ Telemetry is **local-only and off by default**. `HEADROOM_TELEMETRY=on` (or `--t
 |--------|---------|-------------|
 | `--host` | `127.0.0.1` | Host to bind to |
 | `--port` | `8787` | Port to bind to |
+| `--uds` | None | Serve on a Unix domain socket at this path instead of `--host`/`--port`. POSIX only — Windows has no `AF_UNIX` support in Python or asyncio. See [Serving on a Unix socket](#serving-on-a-unix-socket) |
 | `--workers` | `1` | Number of Uvicorn worker processes |
 | `--limit-concurrency` | `1000` | Maximum concurrent connections before Uvicorn returns 503 |
 | `--max-connections` | `500` | Maximum upstream HTTP connections |
@@ -193,6 +194,54 @@ HEADROOM_SAVINGS_PROFILE=balanced HEADROOM_TARGET_RATIO=0.15 headroom proxy
 
 For permanent custom profiles, see the profile definitions in `headroom/agent_savings.py`. Each profile is an `AgentSavingsProfile` dataclass with fields for compression mode, target ratio, turn protection, and pipeline toggles.
 
+## Serving on a Unix socket
+
+`--uds` binds an `AF_UNIX` socket instead of a TCP port. Request handling is
+identical — only the transport changes.
+
+```bash
+headroom proxy --uds ~/.headroom/run/proxy.sock
+```
+
+Two reasons to prefer it over a loopback port:
+
+- **No port to collide with, and no port exposed.** Access is governed by
+  filesystem permissions rather than by anything listening on the network.
+- **Clients that gate features on the API host.** Claude Code v2.1.196+ turns off
+  Remote Control, the 1M context window, and on-demand tool loading when
+  `ANTHROPIC_BASE_URL` names a host other than `api.anthropic.com`. A socket lets
+  the base URL stay first-party while the traffic still arrives at Headroom — see
+  [Remote Control unavailable through custom ANTHROPIC_BASE_URL](/docs/troubleshooting#remote-control-unavailable-through-custom-anthropic_base_url).
+
+Point any Unix-socket-capable client at the path. With curl:
+
+```bash
+curl --unix-socket ~/.headroom/run/proxy.sock http://localhost/health
+```
+
+### Permissions and lifecycle
+
+Headroom creates the socket's parent directory `0700`, so only the owning user can
+reach the socket inside it. A Unix socket carries no credentials of its own, so
+**the directory mode is the access-control boundary** — do not place the socket in
+a world-writable directory such as a bare `/tmp`.
+
+On startup Headroom removes a stale socket left behind by a crashed process, but
+it refuses to start when:
+
+- something is still listening on the path (two proxies would silently split traffic),
+- the path exists and is not a socket (far more likely a typo'd argument pointing
+  at real data than a leftover), or
+- the path exceeds the platform's `sun_path` limit — 108 bytes on Linux, 104 on
+  macOS and the BSDs. Keep it short; a long path fails inside `bind()` with an
+  error that names nothing.
+
+<Callout type="warn">
+  `--uds` is POSIX-only. On Windows the command exits immediately with an error
+  telling you to use `--port`; Python exposes no `socket.AF_UNIX` there and
+  asyncio has no Windows UDS transport.
+</Callout>
+
 ## Configuration in depth
 
 Proxy behavior is set by three layers, **each overriding the one before**:

docs/content/docs/troubleshooting.mdx

@@ -215,11 +215,39 @@ See [issue #746](https://github.com/headroomlabs-ai/headroom/issues/746) for the
 
 ## Remote Control unavailable through custom ANTHROPIC_BASE_URL
 
-**Symptom**: When Claude Code runs with `ANTHROPIC_BASE_URL` set to a custom host (for example, Headroom), the Remote Control menu is absent.
+**Symptom**: When Claude Code runs with `ANTHROPIC_BASE_URL` set to a custom host (for example, Headroom), the Remote Control menu is absent. Invoking `/remote-control` reports `Remote Control is only available when using Claude via api.anthropic.com`.
 
-**Cause**: This is a Claude-side gate. Headroom only receives normal API traffic and can still compress it, but Claude evaluates Remote Control availability before proxy traffic reaches the server.
+**Cause**: A client-side gate, evaluated before any traffic reaches Headroom. Claude Code v2.1.196+ parses `ANTHROPIC_BASE_URL` and compares the host against `api.anthropic.com` exactly, so a loopback address fails it. The check is satisfied by any one of:
 
-**Fix**: Use Headroom for normal proxied API sessions, and launch Claude directly (without `ANTHROPIC_BASE_URL`) when you need Claude Remote Control.
+- `ANTHROPIC_BASE_URL` unset, or naming `api.anthropic.com` as its host, or
+- `ANTHROPIC_UNIX_SOCKET` pointing at a Unix domain socket.
+
+Note that Remote Control does **not** honor `_CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL`, the flag that re-enables the 1M window and on-demand tool loading — it reads the base URL directly. Headroom cannot re-enable Remote Control from the server side the way `--1m` restores the `context-1m` beta header, because the eligibility decision and the bridge connection both happen in the client.
+
+**Fix**: Launch Claude directly, without `ANTHROPIC_BASE_URL`, for sessions that need Remote Control, and use Headroom for the rest.
+
+**Alternative (experimental)**: serve Headroom on a Unix socket and hand Claude Code the socket instead of a URL. The base URL stays first-party, so the gate passes, while the traffic still reaches Headroom:
+
+```bash
+headroom proxy --uds ~/.headroom/run/proxy.sock
+
+# in the session that should be routed
+export ANTHROPIC_UNIX_SOCKET=~/.headroom/run/proxy.sock
+export ANTHROPIC_BASE_URL=http://api.anthropic.com
+claude
+```
+
+<Callout type="warning">
+  This route is unverified end-to-end and is not yet wired into `headroom wrap
+  claude`. Remote Control also depends on a server-side rollout flag and on
+  subscription authentication, so a passing host check is necessary but not
+  sufficient. Claude Code additionally strips `ANTHROPIC_UNIX_SOCKET` and
+  `ANTHROPIC_BASE_URL` from child processes, so a hook that shells out to
+  `claude` bypasses Headroom entirely. Report results on
+  [issue #1779](https://github.com/headroomlabs-ai/headroom/issues/1779).
+</Callout>
+
+The upstream request to allow loopback proxies is tracked at [anthropics/claude-code#76653](https://github.com/anthropics/claude-code/issues/76653).
 
 `ENABLE_TOOL_SEARCH` is unaffected and can stay enabled for context-window savings while routing through Headroom.
 

headroom/cli/proxy.py

@@ -228,6 +228,17 @@ def dashboard(port: int, no_open: bool) -> None:
     envvar="HEADROOM_HOST",
     help="Host to bind to (default: 127.0.0.1, env: HEADROOM_HOST)",
 )
+@click.option(
+    "--uds",
+    default=None,
+    envvar="HEADROOM_UDS",
+    metavar="PATH",
+    help=(
+        "Serve on a Unix domain socket instead of --host/--port. POSIX only. "
+        "Lets a client keep a first-party base URL while its traffic still "
+        "reaches Headroom (env: HEADROOM_UDS)."
+    ),
+)
 @click.option(
     "--port",
     "-p",
@@ -1014,6 +1025,7 @@ def proxy(
     mode: str | None,
     target_ratio: float | None,
     host: str,
+    uds: str | None,
     port: int,
     workers: int,
     limit_concurrency: int,
@@ -1116,6 +1128,17 @@ def proxy(
         OPENAI_BASE_URL=http://localhost:8787/v1 your-app
     """
     _reexec_with_malloc_tuning()
+
+    # Fail before any dependency loading or config work: an unusable --uds is a
+    # typo or an unsupported platform, and both are cheaper to report up front.
+    if uds:
+        from headroom.proxy.uds import UdsError, require_uds_support
+
+        try:
+            require_uds_support()
+        except UdsError as exc:
+            raise click.ClickException(str(exc)) from exc
+
     ensure_proxy_dependencies()
 
     # Import here to avoid slow startup
@@ -1296,6 +1319,7 @@ def proxy(
     config = ProxyConfig(
         host=host,
         port=port,
+        uds=uds,
         rollout=rollout_snapshot,
         anthropic_api_url=provider_api_overrides.anthropic,
         anthropic_extra_headers=resolved_anthropic_extra_headers,
@@ -1612,6 +1636,25 @@ def proxy(
     else:
         tuning_section = ""
 
+    # A socket has no URL, and the client-side wiring for it is a different pair
+    # of env vars, so the banner's URL and Usage blocks both switch shape.
+    if config.uds:
+        listen_display = f"unix:{config.uds}"
+        usage_section = "\n".join(
+            (
+                f"  Claude Code:   ANTHROPIC_UNIX_SOCKET={config.uds} \\",
+                "                 ANTHROPIC_BASE_URL=http://api.anthropic.com claude",
+            )
+        )
+    else:
+        listen_display = f"http://{config.host}:{config.port}"
+        usage_section = "\n".join(
+            (
+                f"  Claude Code:   ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude",
+                f"  Codex / OpenAI: OPENAI_BASE_URL=http://{config.host}:{config.port}/v1 your-app",
+            )
+        )
+
     click.echo(f"""
 ╔═══════════════════════════════════════════════════════════════════════╗
 ║                         HEADROOM PROXY                                 ║
@@ -1620,7 +1663,7 @@ def proxy(
 
 Starting proxy server...
 
-  URL:          http://{config.host}:{config.port}
+  URL:          {listen_display}
   Mode:         {config.mode}
   Optimization: {"ENABLED" if config.optimize else "DISABLED"}
   Caching:      {"ENABLED" if config.cache_enabled else "DISABLED"}
@@ -1641,8 +1684,7 @@ def proxy(
   /v1/projects/.../publishers/... → {vertex_url}
 
 Usage:
-  Claude Code:   ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude
-  Codex / OpenAI: OPENAI_BASE_URL=http://{config.host}:{config.port}/v1 your-app
+{usage_section}
 {memory_section}
 Endpoints:
   GET  /livez      Process liveness

headroom/proxy/models.py

@@ -140,6 +140,9 @@ class ProxyConfig:
     # Server
     host: str = "127.0.0.1"
     port: int = 8787
+    # Serve on this Unix domain socket instead of host:port. POSIX only; see
+    # headroom/proxy/uds.py for why a socket transport exists at all (GH #1779).
+    uds: str | None = None
     # Resolved at this configuration boundary and then injected unchanged.
     rollout: RolloutSnapshot | None = None
     anthropic_api_url: str | None = None  # Custom Anthropic API URL override

headroom/proxy/server.py

@@ -5385,13 +5385,20 @@ def run_server(
     # Resolve upstream API targets for display in the banner (#583).
     api_targets = resolve_api_targets(config.provider_api_overrides)
 
+    if config.uds:
+        listen_display = f"unix:{config.uds}"
+        usage_display = f"ANTHROPIC_UNIX_SOCKET={config.uds} claude"
+    else:
+        listen_display = f"http://{config.host}:{config.port}"
+        usage_display = f"ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude"
+
     if print_banner:
         print(f"""
 ╔══════════════════════════════════════════════════════════════════════╗
 ║                      HEADROOM PROXY SERVER                           ║
 ╠══════════════════════════════════════════════════════════════════════╣
 ║  Version: 1.0.0                                                      ║
-║  Listening: http://{config.host}:{config.port:<5}                                      ║
+║  Listening: {listen_display:<57}║
 ║  Workers: {workers:<3}  Concurrency Limit: {limit_concurrency:<5}                          ║
 ║  Backend: {backend_status:<59}║
 ╠══════════════════════════════════════════════════════════════════════╣
@@ -5413,7 +5420,7 @@ def run_server(
 ║    Conn Pool:       {pool_info:<52}║
 ╠══════════════════════════════════════════════════════════════════════╣
 ║  USAGE:                                                              ║
-║    Claude Code:   ANTHROPIC_BASE_URL=http://{config.host}:{config.port} claude     ║
+║    Claude Code:   {usage_display:<51}║
 ║    Cursor:        Set base URL in settings                           ║
 ╠══════════════════════════════════════════════════════════════════════╣
 ║  ENDPOINTS:                                                          ║
@@ -5485,10 +5492,39 @@ def run_server(
     else:
         app_target = create_app(config)
 
+    # Bind target: a Unix socket when one is configured, otherwise host:port.
+    # uvicorn treats `uds` and `host`/`port` as alternatives, so they are built
+    # here rather than passed together.
+    bind_kwargs: dict[str, Any]
+    uds_path: Path | None = None
+    if config.uds:
+        from headroom.proxy.uds import prepare_uds_path
+
+        uds_path = prepare_uds_path(config.uds)
+        bind_kwargs = {"uds": str(uds_path)}
+    else:
+        bind_kwargs = {"host": config.host, "port": config.port}
+
+    try:
+        _run_uvicorn(app_target, bind_kwargs, workers, limit_concurrency, uvicorn_kwargs)
+    finally:
+        if uds_path is not None:
+            from headroom.proxy.uds import remove_uds_path
+
+            remove_uds_path(uds_path)
+
+
+def _run_uvicorn(
+    app_target: Any,
+    bind_kwargs: dict[str, Any],
+    workers: int,
+    limit_concurrency: int,
+    uvicorn_kwargs: dict[str, Any],
+) -> None:
+    """Hand off to uvicorn. Split out so the bind target stays testable."""
     uvicorn.run(
         app_target,
-        host=config.host,
-        port=config.port,
+        **bind_kwargs,
         log_level="warning",
         workers=workers if workers > 1 else None,  # None = single process (default)
         limit_concurrency=limit_concurrency,