NetBridge

Access internal corporate resources from your laptop by tunneling TCP connections through a remote machine's network position.

┌─────────── Laptop ─────────┐    ┌── Azure App Service ──┐    ┌──────── Win Machine ──────┐
│                            │    │                       │    │                           │
│  Browser      Proxy        │    │ Relay                 │    │  Agent          Internal  │
│  kubectl ◄──► SOCKS5 :1080 │◄──►│ WebSocket Multiplexer │◄──►│  WebSocket ◄──► hosts     │
│  CLI          HTTP  :3128  │    │                       │    │  TCP tunnel               │
│                            │    │                       │    │                           │
└────────────────────────────┘    └───────────────────────┘    └───────────────────────────┘

• A deployed relay — you need a running relay instance and its URL. See Deploying the Relay.
• Azure CLI — install the Azure CLI and run az login before starting the agent or proxy. Tokens are acquired automatically at runtime.
• Azure AD account — your account must belong to a tenant allowed by the relay (NETBRIDGE_ALLOWED_TENANTS).
• A Windows machine (VDI) — with access to the internal resources you want to reach. The agent will be installed on this machine.

Download netbridge.exe and run it on the Windows machine. A dialog will prompt for your relay URL. The agent installs itself, registers for Windows Startup, and connects automatically.

The tray icon shows connection status: green (connected), yellow (connecting), red (disconnected), orange (login required).

Requires Homebrew. If you don't have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install the proxy:

brew tap chrishham/tap
brew install netbridge-socks

Continue with these instructions: homebrew-tap README.

Download netbridge-socks.exe and run it. On first launch a dialog will prompt for your relay hostname. The executable installs itself to %LOCALAPPDATA%\NetBridgeSocks\, registers for Windows Startup, and launches automatically.

The tray icon shows proxy status: green (connected, tunnel working end to end), purple ring (relay reached but the VDI agent is unreachable), yellow (connecting), red (disconnected), orange (login required). The proxy checks the full path to the VDI as soon as it connects, and keeps checking while the agent is missing, so the icon reflects whether traffic can actually flow — not just whether the relay accepted the connection. Right-click the tray icon for options:

• Check Connection Now — re-run the end-to-end check immediately
• Change Relay URL — switch to a different relay and restart
• Login (az login) — re-authenticate with Azure
• View Logs — open the current log file
• Uninstall — remove the app from your system

Configuration is stored in %LOCALAPPDATA%\NetBridgeSocks\config.json and logs in %LOCALAPPDATA%\NetBridgeSocks\logs\.

If your relay restricts destinations and rejects the default health-check target, set "probe_target": "host:port" in config.json to a destination the relay allows.

The proxy exposes two local endpoints:

• SOCKS5 on localhost:1080
• HTTP on localhost:3128

1. Settings → Network Settings → Manual proxy
2. SOCKS Host: localhost, Port: 1080, SOCKS v5
3. Check "Proxy DNS when using SOCKS v5"

# in ~/.kube/config under cluster
clusters:
- cluster:
    server: https://your-k8s-cluster.example.com:6443
    proxy-url: socks5://localhost:1080

# Bash/Zsh
export HTTP_PROXY="http://localhost:3128"
export HTTPS_PROXY="http://localhost:3128"

# git over HTTPS
git config --global http.proxy http://localhost:3128

# Via SOCKS5 (socks5h resolves DNS through the proxy)
curl --proxy socks5h://localhost:1080 https://internal-api.example.com/health

# Via HTTP proxy
curl --proxy http://localhost:3128 https://internal-api.example.com/health

By default the proxy binds to localhost only. To allow connections from other machines:

netbridge-socks --relay <URL> --host 0.0.0.0 --allow-remote --proxy-auth user:pass

--allow-remote requires --proxy-auth to prevent open proxy abuse.

e2e/ drives the full client → proxy → relay → agent → target path. CI runs it from source on Linux for pushes to main and on pull requests, and against the installed Windows exes (e2e-windows.yml) on PRs and before every Windows release; releases publish exactly the exe that passed. See e2e/README.md.

The agent loads configuration from %LOCALAPPDATA%\NetBridge\config.json:

Proxy settings are auto-detected from the system (PAC file / WinHTTP) per target URL. Loopback and link-local addresses are always blocked regardless of configuration. When allowed_destinations is set, only matching destinations are reachable. The deny list is checked first. These are agent-side filters, complementing the relay-side RELAY_ALLOWED_DESTINATIONS / RELAY_DENIED_DESTINATIONS.

The relay is configured entirely through environment variables.

Authentication:

Rate Limiting:

Destination Filtering:

When RELAY_ALLOWED_DESTINATIONS is set only matching destinations are reachable. The deny list is checked first.

Timeouts:

Logging:

Run netbridge-socks --help for all CLI options. The following environment variables tune proxy behavior:

These environment variables are shared between the agent and proxy for connection tuning:

Agent: right-click the tray icon → Change Relay URL. The agent restarts automatically.

Proxy (macOS/Linux): see the homebrew-tap README for config file location.

Proxy (Windows): right-click the tray icon → Change Relay URL. The proxy restarts automatically.

• This is not a shell or RCE tool — it only tunnels TCP connections
• All traffic is encrypted (TLS) between each component and the relay
• No credentials are stored or transmitted — authentication uses Azure CLI tokens at runtime
• Both proxy servers bind to localhost only by default
• Authentication uses Azure AD ARM tokens (az login)
• When behind a TLS-intercepting proxy, prefer --ca-bundle <file> (or NETBRIDGE_CA_BUNDLE env var) to supply your corporate CA certificate instead of disabling verification entirely
• SSL verification can be disabled (--no-verify-ssl) as a last resort — this requires setting NETBRIDGE_ALLOW_INSECURE=1 and weakens security

The relay runs as a Docker container and needs an HTTPS endpoint that supports WebSockets. Two common options:

Azure App Service (Container):

1. Create a Web App for Containers in the Azure Portal
2. Point it at the GHCR image: ghcr.io/chrishham/netbridge-relay:latest
3. Under Settings → Configuration, add the required environment variables (at minimum NETBRIDGE_ALLOWED_TENANTS)
4. Ensure WebSockets are enabled under Settings → Configuration → General settings
5. The relay listens on port 8080 — set this as the container port

Self-hosted (k3s / Docker Compose / any container host):

1. Pull the image: docker pull ghcr.io/chrishham/netbridge-relay:latest
2. Run with the required environment variables:

   docker run -d -p 8080:8080 \
     -e NETBRIDGE_ALLOWED_TENANTS=<your-tenant-id> \
     ghcr.io/chrishham/netbridge-relay:latest

3. Place a reverse proxy (e.g. Traefik, Caddy, nginx) in front to terminate TLS and provide an HTTPS URL with WebSocket support

The relay exposes a /status endpoint you can use as a health check.

Each component is a separate Python package managed with uv:

cd <component>

# Run the component (use --native-tls in corporate environments)
uv run --native-tls <component-name>

# Run tests
uv run --native-tls pytest

Each component is versioned and released independently:

# Release the agent (builds Windows .exe and creates a GitHub Release)
git tag agent-v0.5.0 && git push --tags

# Release the relay (builds and pushes Docker image to GHCR)
git tag relay-v1.0.0 && git push --tags

# Release the socks proxy (runs tests and updates Homebrew formula)
git tag socks-v0.2.0 && git push --tags

# Release the socks proxy Windows exe (builds .exe and creates a GitHub Release)
git tag socks-exe-v1.0.0 && git push --tags