Claude Code With V2RayN: Terminal Proxy Setup Guide

Claude Code runs in a terminal, so configuring a browser proxy alone does not guarantee that its requests will use the same route. The terminal process must inherit the proxy environment variables, or its traffic must be captured by v2rayN TUN mode. This distinction explains why a web page may open normally while Claude Code reports a timeout, authentication failure, or inability to reach the service.

This guide explains how to use v2rayN with Claude Code on a desktop system. It covers subscription import, Xray core selection, system proxy mode, TUN mode, shell environment variables, authentication checks, and practical tests that separate a local configuration problem from a remote network problem. The examples use Windows-style v2rayN menu names where appropriate, but the same networking principles apply on macOS and Linux desktop deployments.

Understand how Claude Code traffic reaches v2rayN

A browser and a terminal can use different proxy paths even when they run on the same computer. Browsers commonly follow the operating system proxy setting or maintain their own proxy configuration. A shell command, Node-based CLI, Python program, or native executable may instead connect directly unless it understands environment variables such as HTTPS_PROXY or is captured by a transparent networking mode.

In ordinary system proxy mode, v2rayN starts local listeners, often an HTTP proxy and a SOCKS proxy. The exact ports are configurable and may differ between installations. Common defaults seen in desktop configurations include HTTP on 10809 and SOCKS on 10808, but you must confirm the values in v2rayN rather than copying a default blindly. Claude Code can use those listeners when its process receives the correct variables.

In TUN mode, v2rayN creates a virtual network interface and routes selected system traffic into the core. Applications do not need to understand HTTP or SOCKS proxy variables because their TCP and UDP connections are intercepted at the network layer. TUN is useful for tools that ignore proxy variables, but it requires administrator permission, a compatible core, correct DNS handling, and careful routing rules.

Prepare v2rayN and import a working subscription

Before troubleshooting Claude Code, make sure v2rayN itself can establish a normal HTTPS connection. A subscription that appears in the server list is not proof that its nodes are usable. The update may have returned an empty response, an expired authorization page, or old configurations with invalid addresses. Select a current group and confirm that at least one node passes a latency or connectivity test.

1. Install v2rayN

   Open the download page, choose the package for Windows, macOS, or Linux, extract it to a persistent folder, and start the desktop client. Avoid placing the application in a temporary download directory that may be cleaned automatically.

2. Add subscription

   Open “Subscription group” → “Add” or the equivalent subscription command, paste the authorized subscription URL, assign a recognizable group name, and save it. Treat the URL as a secret because it may contain account-specific access information.

3. Update nodes

   Run “Update all subscriptions” and wait for the result in the log pane. Confirm that the selected group contains current VMess, VLESS, or other supported entries rather than only an empty list or stale rows.

4. Select active server

   Choose a node, run its connectivity or latency test, and then use “Set as active server.” Selecting a row for testing is not always the same as activating it for outbound traffic.

5. Start the core

   Check that the Xray core starts without a JSON parsing error, port conflict, or missing asset message. Keep the log window visible while making the first Claude Code request.

For a first test, prefer a stable TCP-based configuration such as VLESS with a correctly configured security layer or a compatible VMess transport supplied by your provider. The protocol name alone is not enough: the address, port, UUID, transport, SNI, security parameters, fingerprint, and flow must agree with the server. Do not edit a subscription-generated node repeatedly while diagnosing the terminal; an update can overwrite local changes and make the test result difficult to interpret.

Configure the terminal environment explicitly

Environment variables are usually the clearest way to test a command-line application. They apply to processes launched from that shell and can be removed without changing the whole operating system. For HTTPS traffic through an HTTP proxy, use an address such as http://127.0.0.1:10809. The word “HTTPS” in HTTPS_PROXY describes the destination traffic; it does not necessarily mean that the local proxy listener itself uses TLS.

Windows PowerShell and Command Prompt

In PowerShell, set the variables for the current terminal session before launching Claude Code:

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:ALL_PROXY="socks5://127.0.0.1:10808"
$env:NO_PROXY="127.0.0.1,localhost"
claude

Do not set every proxy variable to a different listener without a reason. Start with HTTP_PROXY and HTTPS_PROXY pointing to the confirmed HTTP port. Add ALL_PROXY only if the application or a child process specifically supports SOCKS. Some libraries prefer lowercase names, so a process that ignores the uppercase form may need both variants:

$env:http_proxy=$env:HTTP_PROXY
$env:https_proxy=$env:HTTPS_PROXY
$env:all_proxy=$env:ALL_PROXY

For Command Prompt, use the following session-scoped commands:

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set NO_PROXY=127.0.0.1,localhost
claude

These settings disappear when the terminal window closes. That is generally safer than writing credentials or proxy values permanently into the user profile. If you need a persistent setting, use the operating system environment-variable editor and document how to remove it later. A stale proxy value can break ordinary development tools after v2rayN is closed.

macOS and Linux shells

In a POSIX-compatible shell, export the variables only for the current session or command:

export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export NO_PROXY="127.0.0.1,localhost"
claude

To limit the scope to one invocation, use:

HTTPS_PROXY=http://127.0.0.1:10809 \
HTTP_PROXY=http://127.0.0.1:10809 \
NO_PROXY=127.0.0.1,localhost \
claude

Some applications support only one proxy scheme, while others distinguish between HTTP CONNECT and SOCKS5. If an HTTP proxy works with a connectivity test but the CLI fails with a proxy protocol error, try the confirmed SOCKS port using a syntax accepted by that client, such as socks5://127.0.0.1:10808. Do not assume that changing the scheme alone can convert an HTTP listener into a SOCKS listener; the listener type and URL scheme must match.

Choose system proxy or TUN mode deliberately

System proxy mode is the preferred starting point because it keeps the traffic boundary narrow. In v2rayN, open “Settings” → “Parameters settings” and inspect the local HTTP and SOCKS listening ports. Then enable the system proxy from the main window or tray menu. The terminal still needs environment variables unless its networking library reads the system proxy automatically. A browser opening a test page proves only that the browser is proxied; it does not prove that Claude Code inherited the same route.

TUN mode is broader. Open “Settings” → “Parameters settings” → “Core type” and choose a TUN-capable configuration supported by the installed v2rayN and Xray versions. Then enable TUN from the main window, approve the elevated-permission prompt, and wait for the virtual interface to appear. The exact label can vary by release, so verify the status indicator and the core log rather than relying on an old screenshot.

• Use system proxy mode when you want only proxy-aware applications or one terminal session to use the route.
• Use TUN mode when the application ignores proxy variables, opens connections through a native networking stack, or requires broader TCP and UDP capture.
• Exclude local networks and administrative addresses where possible, especially if you need access to routers, development servers, containers, or private DNS zones.
• Do not run two unrelated transparent proxy tools at the same time; competing virtual interfaces and DNS handlers can create loops.
• After changing modes, close and relaunch Claude Code so child processes inherit a clean networking state.

Verify the route before starting an AI coding task

Run tests in layers. First confirm that v2rayN is active and that the selected local port is listening. Next test the proxy with a small HTTPS request. Then launch Claude Code from the same terminal session in which the variables were exported. This sequence prevents an authentication error from being mistaken for a node failure.

On Windows, a basic port check can be performed in PowerShell:

Test-NetConnection 127.0.0.1 -Port 10809

On systems with a curl-compatible command, test the local HTTP proxy explicitly:

curl.exe -I --proxy http://127.0.0.1:10809 https://api.anthropic.com

A response such as 401 Unauthorized or 404 Not Found can still be useful at this stage: it shows that the request reached the remote HTTPS service through the proxy path. A local connection refusal, timeout while connecting to 127.0.0.1, or proxy protocol error points back to the v2rayN listener, port number, or local firewall. Do not interpret a successful HTTP status as proof that your Claude Code account is authorized; authentication is a separate layer.

Read errors by layer instead of changing nodes at random

Claude Code may report a generic network message even when the actual failure occurs earlier. Compare the terminal output with the v2rayN log timestamp. If v2rayN records no inbound connection while Claude Code is running, the process probably did not use the environment variables and is not being captured by TUN. If v2rayN records an outbound attempt followed by a TLS or remote reset error, the request reached the core and the investigation should move to node parameters, routing, or upstream availability.

Streaming responses deserve a separate check. A short request may succeed while a long coding session fails because a middlebox closes idle connections or a transport path mishandles long-lived HTTPS responses. Watch whether the first response arrives, whether output stops after a fixed interval, and whether the v2rayN log shows a reconnect or remote reset. Test a stable node and avoid changing protocol, routing, and TUN settings simultaneously.

Keep the terminal proxy setup maintainable

Once Claude Code works, record the working mode in a small private note: the v2rayN release used in 2026, the selected core type, the local HTTP or SOCKS port, whether TUN was enabled, and the shell command used to launch the process. Do not record the subscription URL or API credential in a shared document. This note makes future updates easier because you can compare one known-good state with the new state.

Use a dedicated shell profile or short local launcher only if you understand its scope. A launcher should set the proxy variables, start Claude Code, and leave unrelated applications untouched. When v2rayN is closed, remove stale variables from long-lived terminal sessions before running package managers, source-control tools, or internal services that should use a direct route.

Subscription updates can change node names, addresses, transports, and routing behavior. If a previously working setup breaks immediately after an update, compare the active server and the core log before editing the terminal configuration. If the local port check fails, fix v2rayN first. If the local test passes but the remote service returns an authentication response, fix the account or session rather than replacing the node repeatedly.

• Keep one known-good node for diagnosis instead of testing five variables at once.
• Use the same shell for proxy export, connectivity testing, authentication, and Claude Code startup.
• Check the local listener before investigating remote service responses.
• Prefer temporary environment variables over permanent global settings during initial setup.
• Review TUN DNS and bypass rules after every core or routing change.
• Keep credentials out of command history, screenshots, and shared configuration files.

With these boundaries in place, Claude Code becomes an ordinary proxy-aware terminal workload: the shell decides whether to send traffic to v2rayN, the local listener hands it to the Xray core, routing selects the intended outbound, and the remote service handles authentication independently. That separation makes failures easier to reproduce and keeps a working terminal proxy from becoming an unexplained system-wide networking change.