Fix Cursor CLI Proxy: When export HTTP_PROXY Does Not Work

Many people try to configure Cursor CLI proxy by running export HTTP_PROXY or export HTTPS_PROXY, only to find that agent still cannot call models. This guide explains why that happens and provides a more reliable proxychains4-based fix.

Language: English | 中文

The Easiest Way

Tip

Recommended: Give this document to Codex, Claude Code, Cursor, or another AI coding assistant, tell it your local proxy address, and let it configure Cursor CLI for you.

Use a one-line prompt like this:

My local proxy is socks5://127.0.0.1:7890. Please configure Cursor CLI proxy according to this document.

Replace the proxy address with your real one, for example:

socks5://127.0.0.1:10808
http://127.0.0.1:8080

Problem

On a fresh Linux machine, Cursor CLI may fail with:

Model not available
This model provider is not supported in your region.

This can happen even when a direct proxy test works:

curl -x http://127.0.0.1:10808 https://ipinfo.io/json

The confusing part is that curl can use the proxy, while agent still fails.

The reason is simple: Cursor Agent's real model request path is not necessarily covered by your shell-level HTTP_PROXY / HTTPS_PROXY variables.

The core goal of this guide is to solve one specific problem: Cursor CLI does not reliably use your proxy even after you export HTTP_PROXY in the shell.

After applying this guide:

• agent uses the local proxy by default.
• New terminal sessions do not need manual export HTTP_PROXY / export HTTPS_PROXY.
• Cursor Agent is not forced down to HTTP/1.1.
• Cursor Agent can keep its default network negotiation, usually allowing HTTP/2.
• Real GPT / Claude model requests go through the proxy path as well.

Root Cause

A common workaround is to inject a Node.js script and patch https.globalAgent.

That only covers part of Node's network stack. It may not reliably cover:

• http2
• gRPC
• streaming requests
• internal model-provider request paths

So you may see a half-working state:

• login works
• account info works
• model list works
• real model calls still fail

The approach in this document is different:

• Use proxychains4 as a TCP-level proxy wrapper.
• Keep useHttp1ForAgent: false.
• Route the whole external TCP path of agent through your local SOCKS5 / HTTP proxy.

Final Architecture

The target path is:

agent
  -> proxychains4
    -> local proxy, for example socks5://127.0.0.1:10808
      -> Cursor API / model providers

Not just:

agent
  -> patched https.globalAgent
    -> only some HTTPS requests use the proxy

Requirements

This guide assumes:

1. You are using Linux.
2. Cursor CLI / Cursor Agent is installed, and agent is available.
3. You already have a working local proxy, such as 127.0.0.1:10808.
4. You know whether the proxy is socks5 or http.

The examples below use:

protocol: socks5
host:     127.0.0.1
port:     10808

Preflight Checks

Check agent:

command -v agent

Check proxychains4:

command -v proxychains4

Install it if needed.

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y proxychains4

CentOS / Rocky / RHEL:

sudo yum install -y proxychains-ng

Or:

sudo dnf install -y proxychains-ng

Check your local proxy port:

ss -ltn | rg 10808

Verify the proxy:

curl -x http://127.0.0.1:10808 https://ipinfo.io/json

If this fails, fix your local proxy first.

Configuration

1. Initialize Cursor Agent

Run:

agent about

If you are not logged in yet:

agent login

This should create or confirm these paths:

• ~/.cursor/
• ~/.cursor/cli-config.json
• ~/.local/bin/agent

2. Create a dedicated proxychains config

Create ~/.cursor/proxychains-agent.conf:

mkdir -p ~/.cursor

cat > ~/.cursor/proxychains-agent.conf <<'EOF'
dynamic_chain
quiet_mode
proxy_dns
remote_dns_subnet 224
tcp_read_time_out 15000
tcp_connect_time_out 8000

localnet 127.0.0.0/255.0.0.0
localnet ::1/128
localnet 10.0.0.0/255.0.0.0
localnet 172.16.0.0/255.240.0.0
localnet 192.168.0.0/255.255.0.0

[ProxyList]
socks5 127.0.0.1 10808
EOF

Notes:

• quiet_mode reduces noisy proxychains logs.
• proxy_dns helps avoid DNS leaks.
• localnet prevents loopback and private network traffic from being sent through the proxy.
• [ProxyList] is where you set your real proxy endpoint.

3. Keep HTTP/2 available

Open:

~/.cursor/cli-config.json

Make sure it contains:

"network": {
  "useHttp1ForAgent": false
}

The key point:

• false means Cursor Agent is not forced to use HTTP/1.1.
• Cursor Agent can use its default behavior, usually negotiating HTTP/2 when available.

Check quickly:

rg -n '"useHttp1ForAgent"' ~/.cursor/cli-config.json

4. Locate the active Cursor Agent startup script

Run:

readlink -f ~/.local/bin/agent

You may see something like:

/home/<user>/.local/share/cursor-agent/versions/2026.04.15-dccdccd/cursor-agent

This is the real script currently executed by agent.

5. Back it up

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"
cp "$REAL_AGENT" "${REAL_AGENT}.bak"

6. Patch the startup script

Overwrite $REAL_AGENT with:

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"

cat > "$REAL_AGENT" <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

export CURSOR_INVOKED_AS="$(basename "$0")"

if command -v realpath >/dev/null 2>&1; then
  SCRIPT_DIR="$(dirname "$(realpath "$0")")"
else
  SCRIPT_DIR="$(dirname "$(readlink "$0" || echo "$0")")"
fi

NODE_BIN="$SCRIPT_DIR/node"

if [ -z "${NODE_COMPILE_CACHE:-}" ]; then
  if [[ "${OSTYPE:-}" == darwin* ]]; then
    export NODE_COMPILE_CACHE="$HOME/Library/Caches/cursor-compile-cache"
  else
    export NODE_COMPILE_CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/cursor-compile-cache"
  fi
fi

PROXYCHAINS_BIN=""
if command -v proxychains4 >/dev/null 2>&1; then
  PROXYCHAINS_BIN="$(command -v proxychains4)"
elif command -v proxychains >/dev/null 2>&1; then
  PROXYCHAINS_BIN="$(command -v proxychains)"
fi

PROXYCHAINS_CONFIG="${CURSOR_AGENT_PROXYCHAINS_CONFIG:-$HOME/.cursor/proxychains-agent.conf}"

if [ -n "$PROXYCHAINS_BIN" ] && [ -f "$PROXYCHAINS_CONFIG" ] && [ "${CURSOR_AGENT_DISABLE_PROXYCHAINS:-0}" != "1" ]; then
  exec -a "$0" "$PROXYCHAINS_BIN" -q -f "$PROXYCHAINS_CONFIG" \
    "$NODE_BIN" --use-system-ca "$SCRIPT_DIR/index.js" "$@"
fi

exec -a "$0" "$NODE_BIN" --use-system-ca "$SCRIPT_DIR/index.js" "$@"
EOF

chmod +x "$REAL_AGENT"

7. Confirm the patch

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"
rg -n 'proxychains4|proxychains-agent.conf|CURSOR_AGENT_DISABLE_PROXYCHAINS' "$REAL_AGENT"

You should see these keywords in the startup script.

Verification

Check basic information:

agent about

Test a model request:

agent -p --output-format text --model gpt-5.4-medium hello

Test another provider if available:

agent -p --output-format text --model claude-4.6-opus-max-thinking hello

Model names may change depending on Cursor CLI and your account. If a sample model is unavailable, use a model that your account can access.

Verify that agent no longer depends on shell proxy variables:

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy ALL_PROXY all_proxy
agent about

If this still works, the proxy is coming from proxychains-agent.conf, not from shell export.

Change Proxy Endpoint

Only edit:

~/.cursor/proxychains-agent.conf

Default:

[ProxyList]
socks5 127.0.0.1 10808

Use port 7890:

[ProxyList]
socks5 127.0.0.1 7890

Use another machine:

[ProxyList]
socks5 192.168.1.50 10808

Use an HTTP proxy:

[ProxyList]
http 127.0.0.1 8080

Then start a new agent session:

agent

After Cursor Agent Updates

Cursor Agent updates may replace the real script path:

~/.local/share/cursor-agent/versions/<new-version>/cursor-agent

After an update, check:

readlink -f ~/.local/bin/agent

Then verify whether the patch is still present:

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"
rg -n 'proxychains4|proxychains-agent.conf' "$REAL_AGENT"

If there is no output, repeat the patch step.

Temporary Switches

Disable proxychains for one run:

CURSOR_AGENT_DISABLE_PROXYCHAINS=1 agent

Use another proxychains config for one run:

CURSOR_AGENT_PROXYCHAINS_CONFIG=/path/to/another.conf agent

Rollback

Restore the backed-up startup script:

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"
cp "${REAL_AGENT}.bak" "$REAL_AGENT"
chmod +x "$REAL_AGENT"

If you only need an emergency fallback, you can change:

"useHttp1ForAgent": false

back to:

"useHttp1ForAgent": true

This forces HTTP/1.1. It may work around some issues, but it is not the main solution recommended here.

Troubleshooting

If agent about hangs:

command -v proxychains4
test -f ~/.cursor/proxychains-agent.conf && echo ok
ss -ltn | rg '10808|7890|8080'

If model list works but real model calls still fail:

REAL_AGENT="$(readlink -f ~/.local/bin/agent)"
rg -n 'proxychains4|proxychains-agent.conf' "$REAL_AGENT"

If you changed the port but Cursor still uses the old one:

sed -n '1,80p' ~/.cursor/proxychains-agent.conf

Make sure you edited the Cursor-specific config, not only:

/etc/proxychains4.conf

If agent works but curl does not use the proxy, that is expected. This guide only configures Cursor Agent. Other tools such as curl, git, npm, and pip still need their own proxy configuration.

Checklist

Before considering the setup complete, check:

1. agent is installed and logged in.
2. proxychains4 is installed.
3. The local proxy port is working.
4. ~/.cursor/proxychains-agent.conf exists and points to the correct endpoint.
5. ~/.cursor/cli-config.json has useHttp1ForAgent set to false.
6. The active cursor-agent startup script contains the proxychains4 logic.

Summary

The fix is not simply "set HTTP_PROXY" or "force HTTP/1.1".

The more reliable approach is to route Cursor Agent through proxychains4 + local proxy at the TCP layer. This keeps Cursor Agent's default network behavior while avoiding the incomplete coverage of patching only https.globalAgent.

---