[BUG] sandbox: SOCKS5 proxy requires authentication that BSD nc cannot negotiate, breaking SSH git operations

I think this is an issue that exists in 2.1.186 and higher. I am still seeing it in 2.1.191.

The authentication token is injected into HTTP_PROXY, ALL_PROXY but it is not set into GIT_SSH_COMMAND (and probably doesn't get supported as pointed out in the issue above).

The root cause is in sandbox-utils.ts generateProxyEnvVars(). On macOS, GIT_SSH_COMMAND is set unconditionally with nc -X 5, even when proxyAuthToken is set:

if (platform === 'macos') {
  // macOS: use BSD nc SOCKS5 proxy support (-X 5 -x). nc has no SOCKS5
  // auth, so when proxyAuthToken is set, git-over-ssh fails at the SOCKS
  // handshake — use git-over-https (HTTP_PROXY carries the credential).
  envVars.push(
    `GIT_SSH_COMMAND=ssh ${sshMuxOverride} -o ProxyCommand='nc -X 5 -x localhost:${socksProxyPort} %h %p'`,
  )
}

The comment documents the known incompatibility but the code still sets the broken value. This regressed when PR #310 (merged June 15) added proxy authentication. The Linux path handles auth correctly via socat --proxyauth; the macOS path does not.

The simplest fix would be to skip GIT_SSH_COMMAND on macOS when proxyAuthToken is set:

if (platform === 'macos' && !proxyAuthToken) {
  envVars.push(
    `GIT_SSH_COMMAND=ssh ${sshMuxOverride} -o ProxyCommand='nc -X 5 -x localhost:${socksProxyPort} %h %p'`,
  )
}

Workaround: Add a SessionStart hook to override the injected variable via CLAUDE_ENV_FILE:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'export GIT_SSH_COMMAND=ssh' >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

I tried the workaround suggested by @cblecker , but it did not work for me. ~Instead, I found I needed to unset the env var:~ Actually, this is also not a viable workaround.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'unset GIT_SSH_COMMAND' >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Confirming the same root cause on Claude Code 2.1.241, macOS, and adding one more data point that may be relevant to the fix.

Repro was via plain ssh, not git — so this bug isn't limited to git-over-SSH:

• ssh user@host (no GIT_SSH_COMMAND involved at all) fails outright with Operation not permitted on the raw connect, even to a host already present in sandbox.network.allowedDomains. Non-HTTP(S) traffic apparently never gets a path through the sandbox unless something explicitly routes it via the SOCKS proxy.
• Manually reproducing the exact GIT_SSH_COMMAND wrapper (ssh -o ProxyCommand='nc -X 5 -x localhost:<port> %h %p' ...) against a plain ssh target hits the identical This proxy requires authentication, and this client did not offer an authentication method failure @cflee and @cblecker already diagnosed.
• To isolate whether "give the proxy real SOCKS5 auth" is sufficient on its own, I hand-rolled a minimal SOCKS5 client in Python that does the RFC 1929 username/password subnegotiation using the credentials embedded in $HTTPS_PROXY (http://srt.<token>:<password>@localhost:<port>), then issues the CONNECT for the SSH target on port 22 and relays stdin/stdout. Auth succeeded (no more auth-negotiation error) and the CONNECT reply came back success — but no bytes ever arrived from the far end; the SSH client just hung to Connection timed out during banner exchange.

That last point suggests @cblecker's proposed fix (skip injecting GIT_SSH_COMMAND on macOS when proxyAuthToken is set) may only get git-over-SSH back to failing cleanly rather than actually working, since the SOCKS proxy's data-plane doesn't appear to forward arbitrary TCP (port 22) even once the auth handshake itself succeeds — worth checking whether the proxy's SOCKS5 CONNECT handler actually opens/relays a real upstream socket for non-HTTP(S) destinations, or only accepts the handshake and drops the stream. Happy to share the throwaway repro script if useful.

Workaround in use meanwhile: dangerouslyDisableSandbox: true per SSH call (same as the thread's conclusion) — no config-level fix found that restores sandboxed SSH.

Disclaimer: this comment is all-Opus
Extracting code from Claude Code was made by Opus in auto mode. Sorry, if this breaks TOS, but it was autonomous Opus.

---

Adding a data point that contradicts the thread's current conclusion: there
is a config-level workaround that restores git-over-SSH inside the
sandbox. The difference is the protocol — HTTP CONNECT works where SOCKS5
does not.

Tested on Claude Code 2.1.252, macOS 26.6.2 (Darwin 25.6.0, arm64), with
sandbox.enabled: true in ~/.claude/settings.json. Note that config also
sets enableWeakerNetworkIsolation: true; the raw-TCP and DNS denials below
still apply, but flagging it since it is a network-policy setting and may
affect what others reproduce.

HTTP CONNECT to the same port forwards port 22 fine

The 2026-08-23 comment reports that a hand-rolled SOCKS5 client with RFC 1929
auth completes the handshake but never relays data (Connection timed out
during banner exchange), and concludes the proxy's data plane may not
forward arbitrary TCP.

That does not hold for the HTTP CONNECT path on the same port. Using a
ProxyCommand that issues CONNECT <host>:22 with a
Proxy-Authorization: Basic header built from the credentials already
present in $HTTP_PROXY, SSH connects and authenticates end to end:

# injected ProxyCommand (nc -X 5, no credentials)
$ command git ls-remote origin HEAD
ssh_dispatch_run_fatal: Connection to UNKNOWN port 65535: Broken pipe
fatal: Could not read from remote repository.

# same command, same sandbox, HTTP CONNECT ProxyCommand with Basic auth
$ GIT_SSH_COMMAND="ssh -o ControlMaster=no -o ControlPath=none \
    -o ProxyCommand='/path/to/helper.py %h %p'" command git ls-remote origin HEAD
<sha>    HEAD

(command git because the shell function shown at the end of this comment
is what I now run day to day; without it, plain git produces the first
result.)

A full git fetch over the same tunnel also succeeds. So the proxy's
CONNECT handler does open and relay a real upstream socket to port 22 —
whatever fails in the SOCKS5 path is specific to SOCKS5, not to the
destination port.

I did not retest authenticated SOCKS5 myself, so I am not claiming it is
broken — only that HTTP CONNECT is a working alternative.

The macOS and Linux branches differ in both protocol and authentication

This is visible in the shipped 2.1.252 binary. Extracted with grep -a and
line-broken for readability, otherwise verbatim:

if (U === "macos")
  N.push(`GIT_SSH_COMMAND=ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand='nc -X 5 -x localhost:${t} %h %p'`);
else if (U === "linux" && e) {
  let M = o ? `,proxyauth=${x}:${o}` : "";
  N.push(`GIT_SSH_COMMAND=ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand='socat - PROXY:localhost:%h:%p,proxyport=${e}${M}'`);
}

The identifiers are minified, but reading ${t}/${e} as the proxy port and
${x}/${o} as the proxy credentials: Linux gets an HTTP CONNECT proxy
(socat's PROXY: address) with proxyauth, while macOS gets SOCKS5
with no credentials at all. That asymmetry lines up exactly with the
observed behaviour, and it is not something the macOS branch could fix by
passing credentials to nc — Apple's nc only has -X proto and
-x addr[:port], with no proxy-authentication option.

Why the two workarounds proposed earlier cannot work

export GIT_SSH_COMMAND=ssh and unset GIT_SSH_COMMAND both leave ssh
attempting a direct connection, and the sandbox blocks that two ways
independently:

$ nc -v -w 6 github.com 22
nc: getaddrinfo: nodename nor servname provided, or not known

$ nc -v -w 6 140.82.121.4 22
nc: connectx to 140.82.121.4 port 22 (tcp) failed: Operation not permitted

DNS does not resolve inside the sandbox, and raw TCP to any non-localhost
address is denied at the OS level. Everything must go through the local
proxy. This also means the proposed fix of skipping the GIT_SSH_COMMAND
injection when proxyAuthToken is set would only make git fail differently,
as the 2026-08-23 comment anticipated.

Also worth noting: no ssh-side configuration can override it

• ProxyCommand in ~/.ssh/config is ignored — the injected

-o ProxyCommand on the command line takes precedence. Confirmed with
ssh -G -o ProxyCommand='CLI-WINS-TEST', which reports the CLI value even
when a matching Host block sets its own.

• git config core.sshCommand is ignored — the GIT_SSH_COMMAND

environment variable wins.

So the override has to happen in the environment of the git invocation
itself.

Helper

Standard library only, no third-party dependencies; any python3 on PATH
will do. Reads the proxy address and credentials from $HTTP_PROXY at run
time (necessary — both the port and the token change per session), and falls
back to a direct nc when HTTP_PROXY is unset, so the same config is safe
outside the sandbox.

#!/usr/bin/env python3
"""SSH ProxyCommand: HTTP CONNECT tunnel with Basic auth from $HTTP_PROXY."""
import base64, os, socket, sys, threading
from urllib.parse import unquote, urlparse

BUF = 65536


def write_all(fd, data):
    """os.write() may write fewer bytes than asked for on a pipe."""
    while data:
        data = data[os.write(fd, data):]


def connect_through_proxy(proxy_url, host, port):
    u = urlparse(proxy_url)
    if not u.hostname or not u.port:
        sys.exit(f"cannot parse a proxy address out of {proxy_url!r}")

    sock = socket.create_connection((u.hostname, u.port), timeout=15)

    req = f"CONNECT {host}:{port} HTTP/1.1\r\nHost: {host}:{port}\r\n"
    if u.username:
        # urlparse leaves the userinfo percent-encoded.
        cred = f"{unquote(u.username)}:{unquote(u.password or '')}"
        token = base64.b64encode(cred.encode()).decode()
        req += f"Proxy-Authorization: Basic {token}\r\n"
    sock.sendall((req + "\r\n").encode())

    resp = b""
    while b"\r\n\r\n" not in resp:
        chunk = sock.recv(4096)
        if not chunk:
            sys.exit("proxy closed the connection during CONNECT")
        resp += chunk

    head, _, rest = resp.partition(b"\r\n\r\n")
    status = head.split(b"\r\n", 1)[0].decode(errors="replace")
    if " 200" not in status:
        sys.exit(f"proxy CONNECT failed: {status}")

    sock.settimeout(None)
    return sock, rest


def main():
    host, port = sys.argv[1], sys.argv[2]

    proxy_url = os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy")
    if not proxy_url:
        try:
            os.execvp("nc", ["nc", host, port])
        except OSError as exc:
            sys.exit(f"no HTTP_PROXY set and nc is unusable: {exc}")

    sock, rest = connect_through_proxy(proxy_url, host, port)
    if rest:
        write_all(1, rest)

    # Downstream (proxy -> stdout) on a thread. When the server closes there is
    # nothing left to flush -- stdout is a raw fd -- and the main thread is
    # parked in a blocking read on stdin with no way to be signalled, so tear
    # the process down from here.
    def downstream():
        try:
            while True:
                data = sock.recv(BUF)
                if not data:
                    break
                write_all(1, data)
        except OSError:
            pass
        os._exit(0)

    threading.Thread(target=downstream, daemon=True).start()

    # Upstream (stdin -> proxy) on the main thread. ssh keeps both pipes open
    # for the life of the connection, so EOF here means ssh is gone: half-close
    # the socket and exit rather than waiting on a peer nobody will read.
    try:
        while True:
            data = os.read(0, BUF)
            if not data:
                break
            sock.sendall(data)
    except OSError:
        pass

    try:
        sock.shutdown(socket.SHUT_WR)
    except OSError:
        pass
    os._exit(0)


if __name__ == "__main__":
    main()

Wired up as a shell function, so it applies only inside the sandbox and only
when the broken value was actually injected:

git() {
  if [[ -n $HTTP_PROXY && "$GIT_SSH_COMMAND" == *"nc -X 5"* ]]; then
    GIT_SSH_COMMAND="ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand='$HOME/.local/bin/ssh-http-connect-proxy.py %h %p'" command git "$@"
  else
    command git "$@"
  fi
}

Suggested refinement to the fix

Rather than skipping the injection when proxyAuthToken is set, the macOS
branch could emit a ProxyCommand that speaks HTTP CONNECT with the
credentials — i.e. give macOS the equivalent of what the Linux branch above
already does with socat - PROXY:...,proxyauth=<user>:<pass>. Since nc
cannot express proxy authentication, that needs a different tool or a small
bundled helper, but the transport itself clearly works.

Confirming this is unchanged on 2.1.259 (macOS Darwin 25.5.0, arm64, sandbox.enabled: true, enableWeakerNetworkIsolation: true), and adding a one-line config workaround that I did not see in the thread — no helper script, no shell function, no dangerouslyDisableSandbox.

The injected value and the refusal are byte-identical to what's already documented above, so just the delta:

GIT_SSH_COMMAND=ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand='nc -X 5 -x localhost:<port> %h %p'

$ nc -w 5 -X 5 -x localhost:<port> github.com 22 </dev/null
SSH-2.0-policy_refusal
...This proxy requires authentication, and this client did not offer an authentication method, so the connection was refused.

Still the same SSH-2.0-policy_refusal banner reported on 2026-08-23, and HTTPS_PROXY in the same environment still carries user:secret@localhost:<port> — so the credential is present and simply not handed to the SSH path, exactly as diagnosed.

Workaround: rewrite SSH remotes to HTTPS, in git config

The 2026-09-01 comment establishes that the proxy's HTTP CONNECT path forwards port 22 fine while SOCKS5 does not. If you only need git (not arbitrary ssh), you don't need a CONNECT helper at all — you can avoid the SSH transport entirely and let HTTPS_PROXY do the work, which it already does correctly:

git config --global url."https://github.com/".insteadOf "git@github.com:"
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"

Verified in-sandbox on 2.1.259 — the SSH-form URL is rewritten and resolves:

$ git ls-remote git@github.com:anthropics/claude-code.git HEAD
f173a697aa6486945f1b9c4aa9ce5383d2c87db6	HEAD

(The identical https:// URL returns the same SHA, so this is the rewrite working, not a fallback.)

Caveats, so nobody adopts it and then blames it:

• Needs an HTTPS credential helper for private repos — and it has to be gh auth setup-git. The macOS osxkeychain helper is not usable here: the keychain is unreachable inside the sandbox (#87008). My git ls-remote above is an anonymous public read and it still printed failed to store: 100001 twice from the configured osxkeychain helper, so anyone relying on it for a private repo will get auth prompts rather than key auth. gh's token reads fine in-sandbox. Public reads need no credentials at all, as above.
• It is global git config, so it applies outside the sandbox too. That's usually fine (HTTPS to GitHub works everywhere), but it does change behaviour for anyone relying on SSH key auth or on signed pushes over SSH in normal terminals. Scope it with --local per repo, or a conditional include, if that matters.
• Only covers git. Plain ssh user@host is still broken — see the 2026-08-23 comment; insteadOf cannot help there.

Not a fix, but it's a two-line change with no script to maintain, so it may be the cheapest unblock for the git-only case while the macOS ProxyCommand branch is sorted out.

One note on the interaction with excludedCommands

git and ssh are both in my sandbox.excludedCommands, and the injected GIT_SSH_COMMAND reaches them anyway — an excluded git still runs with the full proxy environment applied. That's a separate defect (#89931, where I've posted a sandbox-off control showing the injection is sandbox-specific), but it's worth knowing here: putting git in excludedCommands is not a workaround for this issue, because the variable is inherited regardless.

The SessionStart + $CLAUDE_ENV_FILE workaround does work, on 2.1.263. Not contradicting @jthurne's report, that was 2.1.191 back in June and plenty has moved since.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'export GIT_SSH_COMMAND=ssh' >> \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Fresh session after that, sandboxed, no dangerouslyDisableSandbox:

$ env | grep GIT_SSH_COMMAND
GIT_SSH_COMMAND=ssh

$ git ls-remote git@github.com:me/myrepo.git HEAD
1dd7359e828398d9292bac64398d2fe43126ba1c	HEAD

git fetch and git push over SSH both work too. I pushed the commit that added this hook with the hook active, which felt appropriately circular.

Which channel you use matters

This is the part I hadn't seen spelled out, and it cost me a session to work out.

I first tried the obvious thing, setting GIT_SSH_COMMAND: "ssh" in the env block of settings.json. That does not work. Settings env is applied before the proxy vars get injected, so the injected value still wins and you get the same broken pipe, with your correct value sitting right there in settings.json looking innocent.

$CLAUDE_ENV_FILE is read afterward, into a cached session-environment script, and it wins. Same variable, same value, different timing. It's only populated for SessionStart, Setup, CwdChanged and FileChanged hooks, so the hook event isn't incidental.

Caveat, because this won't help everyone

Setting GIT_SSH_COMMAND=ssh only hands resolution back to your ~/.ssh/config. It doesn't create a path to port 22 on its own.

It worked for me because I already run my own SOCKS5 proxy (gost) on 127.0.0.1:1080 with a host:port allowlist, plus a ProxyCommand in ssh config that routes agent sessions through it. Localhost is exempt from the sandbox's port 22 block, so that relay works fine sandboxed. Bare ssh is enough to get out of the way and let it do its job.

If the harness proxy is your only way out, you still need the CONNECT helper from @jmakinen81's comment. So this fixes the narrow case of "I have my own relay and the injected variable is clobbering it." Probably a small group, but the clobbering itself is squarely this bug: no user configuration at any layer can beat that variable, which is why it took three sessions to characterize what looked like a plain network failure.

One more data point on the refusal, unchanged from what's already documented: the proxy answers the handshake itself as SSH-2.0-policy_refusal and drops the connection after KEXINIT, so it never dials the real host. Worth knowing that a denied host looks different, SOCKS error 2 on :443 through the same proxy. That distinction saved me from chasing sandbox.network.allowedDomains, which has nothing to do with it.

Tested on 2.1.263, macOS Darwin 25.5.0 arm64, sandbox.enabled: true.

Same on Claude Code 2.1.224 (Homebrew cask), macOS (Darwin 27.0.0, arm64), sandbox.enabled: true. The injected value and the refusal match the report above.

One data point on excludedCommands I have not seen in this thread. With both "git *" and "gh *" listed, only gh leaves the sandbox: a bare gh auth status reads the login keychain. A bare git call still gets the sandbox filesystem policy, not only the proxy env from #89931:

$ git -C ~/Library/Preferences rev-parse --is-inside-work-tree
fatal: Unable to read current working directory: Operation not permitted

So on macOS excludedCommands is no workaround for git.

Confirming authenticated SOCKS5 works end to end here, answering the question @folotp raised on 2026-08-23 and @jmakinen81 left untested on 2026-09-01 ("I did not retest authenticated SOCKS5 myself").

Tested against the sandbox's own local proxy (the same one nc targets, from a live $HTTP_PROXY), with socat's SOCKS5-CONNECT address and separately with ncat's --proxy-type socks5, each doing a full git push:

GIT_SSH_COMMAND='ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand="socat - SOCKS5-CONNECT:127.0.0.1:<SOCKS_PORT>:%h:%p,socksuser=<USER>,sockspass=<PASS>"' git push origin <branch>

GIT_SSH_COMMAND='ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand="env NCAT_PROXY_AUTH=<USER>:<PASS> ncat --proxy 127.0.0.1:<SOCKS_PORT> --proxy-type socks5 %h %p"' git push origin <branch>

The commands above use 127.0.0.1. ncat failed here against localhost, resolving to ::1 first with nothing listening there; socat had no such issue with the same string.

Tested on Claude Code 2.1.231, macOS 26.6.2 (Darwin 25.6.0, arm64), sandbox.enabled: true.

Still reproduces on Claude Code 2.1.284, macOS, in headless claude -p turns whose sandbox is set through --settings (sandbox.enabled: true, allowUnsandboxedCommands: false, network.allowedDomains: ["*"]).

• The injected GIT_SSH_COMMAND is unchanged: ssh -o ControlMaster=no -o ControlPath=none -o ProxyCommand='nc -X 5 -x localhost:<port> %h %p'. The auth token is present in HTTPS_PROXY / ALL_PROXY but not in the SSH path.
• git ls-remote git@github.com:<owner>/<private-repo>.git HEAD fails with Received disconnect from UNKNOWN port 65535:1: This proxy requires authentication, and this client did not offer an authentication method, so the connection was refused. (exit 128).
• Overriding GIT_SSH_COMMAND with plain ssh -o BatchMode=yes fails too (Could not resolve hostname github.com), since DNS only works through the proxy.
• HTTPS through the same sandbox works: git ls-remote https://github.com/<owner>/<private-repo>.git HEAD with gh auth git-credential as the credential helper returns the ref.

Workaround in use until this is fixed: per-process git config (GIT_CONFIG_COUNT / GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n) that maps git@github.com: and ssh://git@github.com/ to https://github.com/, plus credential.https://github.com.helper=!gh auth git-credential. When the global git config rewrites https://github.com/ to SSH via url.<ssh>.insteadOf, it also needs GIT_CONFIG_GLOBAL=/dev/null with the rest of the global config re-added at command scope, because git applies only one insteadOf rewrite.

Still present on macOS 27.0.1 (arm64) with Claude Code 2.1.289 (desktop app, Code tab) and the 2.1.288 CLI. I also checked the 2.1.292 darwin-arm64 build, the latest on npm as of 2026-10-07: the macOS branch still injects ProxyCommand='nc -X 5 -x localhost:<port> %h %p' without credentials, so a fix has not shipped yet.

Three fixes are open in sandbox-runtime and still awaiting review: anthropics/sandbox-runtime#452, anthropics/sandbox-runtime#482, anthropics/sandbox-runtime#516.