Skip to content

cs-proxy

SOCKS5 and HTTP proxy management via SSH tunnel to a GitHub Codespace.

Usage

cs-proxy [options] <command> [args]

Global Options

Flag Description Default
-p, --port SOCKS5 proxy port 1080
-n, --num-proxies Number of codespaces/tunnels (1-2 on free tier); each gets its own port 1
-c, --codespace Codespace name auto-select
-l, --location Region for new Codespace: EastUs, WestUs2, WestEurope, SouthEastAsia. Repeat for multiple: -l WestEurope -l EastUs none
-v, --verbose Verbose output off
--dry-run Show what would happen without making changes off

Commands

Tunnel Management

start

Start a SOCKS5 proxy tunnel to a Codespace.

cs-proxy start                                # auto-select or create one codespace
cs-proxy start -c my-codespace-name          # use a specific codespace
cs-proxy start -p 9050                       # use a non-default port
cs-proxy -n 2 start                          # two codespaces, two tunnels (1080 + 1081)
cs-proxy -n 2 start -l WestEurope -l EastUs  # pin each to a specific region
cs-proxy --dry-run start                     # preview what would happen

Starts an SSH tunnel with SOCKS5 dynamic port forwarding on 127.0.0.1:<port>. The tunnel runs in the background with automatic reconnection using exponential backoff and jitter.

When -n 2 is used, a second codespace is created (or reused) and a second independent tunnel is started on the next port (socks_port + 1). Each tunnel has a different exit IP. Use -l once per codespace to pin each to a region: EastUs, WestUs2, WestEurope, SouthEastAsia.

Circuit breaker: If a tunnel fails 3 consecutive health checks, it is automatically marked as dead and stops retrying. Use cs-proxy restart to reset it.

stop

Stop the proxy tunnel and HTTP proxy.

cs-proxy stop
cs-proxy --dry-run stop   # preview what would stop

restart

Restart the proxy tunnel.

cs-proxy restart

status

Show tunnel status, Codespace state, and exit IP.

cs-proxy status
cs-proxy status --watch   # auto-refresh every 2 seconds

When multiple codespaces are tracked, shows each tunnel's port, health, and exit IP side by side.

Diagnostics

check

Run diagnostics and report configuration/dependency health.

cs-proxy check

Checks:

  • gh CLI installed and authenticated
  • ssh, curl, proxychains4 installed
  • Config directory and file present
  • SSH key generated
  • SOCKS5/HTTP ports available
  • State file readable

Returns exit code 0 if all checks pass, 1 if any issues are found.

doctor

Run diagnostics, with an optional safe local repair pass.

cs-proxy doctor
cs-proxy doctor --fix

With --fix, doctor ensures the config directory exists, reconciles stale tunnel state, regenerates proxychains.conf, and creates a config file if one is missing.

doctor --fix only repairs local files/state. It still returns nonzero if required dependencies or authentication are missing.

pool

Inspect and manage locally tracked SSH tunnel pool entries.

cs-proxy pool list
cs-proxy pool rotate       # print one healthy tunnel port
cs-proxy pool drain 1081   # mark a tunnel as draining

pool rotate is intentionally simple so scripts can consume it directly.

Two-Hop Chains

chain create

Create a two-hop Codespaces chain definition.

cs-proxy chain create eu-us --hop WestEurope --hop EastUs
cs-proxy chain create eu-us --hop eu:WestEurope --hop us:EastUs

chain start

Start the chain and expose a local SOCKS endpoint.

cs-proxy chain start eu-us --port 1080

Traffic flows from the local SOCKS port to the first Codespace, then through a WebSocket relay to the second Codespace, which opens the final outbound connection.

chain start waits for the local port forwards to accept connections before reporting the chain as started.

chain status

Show running chain state.

cs-proxy chain status
cs-proxy chain status eu-us

chain stop

Stop local forwarding and remote chain relay processes.

cs-proxy chain stop eu-us

Chain mode is experimental and intentionally capped at two hops.

Named Accounts

account add

Store a named GitHub account that reads its PAT from an environment variable.

export GH_TOKEN_EU=...
cs-proxy account add eu --token-env GH_TOKEN_EU

Raw PATs are rejected as command arguments. Use environment variables so tokens do not land in shell history.

account list

List configured account labels and token environment variable names.

cs-proxy account list

account remove

Remove an account label.

cs-proxy account remove eu
cs-proxy account rm eu

HTTP Proxy

http

Start an HTTP proxy (tinyproxy) that connects upstream to the SOCKS5 tunnel.

cs-proxy http

This is useful for tools that support HTTP proxies but not SOCKS5. The HTTP proxy listens on port 8080 by default.

Configuration

env

Print environment export statements for shell integration.

eval $(cs-proxy env)

Exports http_proxy, https_proxy, ALL_PROXY, and SOCKS_PROXY.

burp

Print Burp Suite upstream proxy configuration.

cs-proxy burp

pac

Generate a Proxy Auto-Config (PAC) file for browser routing.

cs-proxy pac > ~/.config/cs-proxy/proxy.pac

The PAC script routes local addresses directly and sends everything else through the SOCKS5 proxy. Point your browser to file:///Users/you/.config/cs-proxy/proxy.pac.

proxychains

Generate a proxychains4 configuration file.

cs-proxy proxychains

completion

Generate shell completion scripts.

cs-proxy completion bash   # bash completion
cs-proxy completion zsh    # zsh completion

set

Set a configuration value.

cs-proxy set socks_port 9050
cs-proxy set codespace_name my-codespace

config

Open the configuration file in your $EDITOR.

cs-proxy config

Codespace Management

list

List available Codespaces.

cs-proxy list

create

Create a new Codespace interactively.

cs-proxy create

teardown

Stop the proxy tunnel(s) and shut down all managed Codespaces (compute stops, storage is preserved — no billing).

cs-proxy teardown     # stops all tunnels and all tracked codespaces

down

Stop the proxy tunnel(s), shut down, and permanently delete all managed Codespaces.

cs-proxy down         # stops tunnels, then prompts to confirm deletion

This is the "nuclear option" for cleaning up after a session. It stops tunnels, stops codespaces, then asks for confirmation before permanently deleting them.

name

Get or set the current Codespace name.

cs-proxy name                    # show current
cs-proxy name my-codespace       # set

Utilities

ssh

Open an SSH session to a Codespace.

cs-proxy ssh          # auto-selects; shows numbered menu if multiple codespaces tracked
cs-proxy ssh 2        # connect to the second tracked codespace by index
cs-proxy ssh my-cs    # connect to a specific codespace by name

run

Run a command through the proxy.

cs-proxy run curl https://ifconfig.me

keygen

Generate an SSH keypair for Codespace authentication.

cs-proxy keygen

split

Set up split tunneling routes.

cs-proxy split

logs

Show tunnel logs.

cs-proxy logs
cs-proxy logs 100     # last 100 lines