GooseRelayVPN

GooseRelayVPN

راهنمای فارسی (Persian)

A SOCKS5 VPN that tunnels raw TCP through a Google Apps Script web app to your own small VPS exit server. To anything on the network path your client only ever talks TLS to a Google IP with SNI=www.google.com. Everything in flight is AES-256-GCM encrypted end-to-end — Google never sees plaintext and never holds the key.

⚠️ You need a small VPS for the exit server. Unlike pure-Apps-Script proxies, this project tunnels raw TCP — anything SOCKS5 can carry — so a real net.Dial has to happen somewhere. A small $4/month VPS is plenty. In exchange you can tunnel SSH, IMAP, custom protocols, anything — not just HTTP.

Table of Contents

• How It Works
• Step-by-Step Setup Guide
• LAN Sharing (Optional)
• Increase capacity with multiple deployments (recommended)
• Configuration
• Updating
• Architecture
• Threat model
• Project Files
• Troubleshooting
• Security Tips
• Contributing
• Support This Project
• Disclaimer
• Special Thanks
• License

How It Works

Browser/App
  -> SOCKS5  (127.0.0.1:1080)
  -> Zstd-compressed + AES-256-GCM frame batches
  -> HTTPS to a Google edge IP   (SNI=www.google.com, Host=script.google.com)
  -> Apps Script doPost()        (dumb forwarder, never sees plaintext)
  -> Your VPS :8443/tunnel       (decrypts, demuxes by session_id, dials target)
  <- Same path in reverse via long-polling

Your application sends TCP bytes through the SOCKS5 listener on your computer. The client groups them into batches of frames, Zstandard-compresses each batch (for compressible traffic such as plain HTTP or JSON APIs this reduces the body size by up to 65%, keeping you further from Apps Script's daily quota limits), then seals the whole batch under a single AES-256-GCM envelope and POSTs it over a domain-fronted HTTPS connection to your Apps Script web app. The Apps Script is a ~30-line script that forwards the body verbatim to your VPS — it never decrypts and the AES key never touches Google. Your VPS decrypts, dials the real target, and pumps bytes back along the same path. The filter sees only TLS to Google.

Apps Script daily quota. Each Google account has a UrlFetch quota of about 20,000 executions per day on the free tier — shared across every deployment under that account, not per deployment. The quota resets at midnight Pacific (≈10:30 AM Iran time in summer, ≈11:30 AM in winter). The Zstd compression above is what stretches that quota the furthest.

---

Step-by-Step Setup Guide

Step 1: Get a VPS

You need a VPS with a public IP. Linux or Windows Server — any provider works.

Step 2: Get the binaries

You need two separate programs:

• goose-client — runs on your own computer. This is what you run every day.
• goose-server — runs on your VPS. You set it up once and leave it running.

Linux VPS shortcut: If your exit server is Linux and you have root, the installer script below bundles Steps 2–7 for the server (download, config, tunnel key, systemd unit, firewall) into one command. You still need to set up the client and Apps Script (Steps 5 and 8+) on your own machine.

bash <(curl -Ls https://raw.githubusercontent.com/Kianmhz/GooseRelayVPN/main/scripts/goose-server.sh)

The script verifies the release tarball against its published SHA256SUMS.txt before installing, generates a fresh tunnel_key you'll paste into the client config, and exposes install / update / uninstall / reconfigure menus on re-run.

Option A — Download a pre-built release (recommended):

1. Go to the Releases page.

2. Download the right archive for your OS:

   • Windows: GooseRelayVPN-client-vX.Y.Z-windows-amd64.zip
   • macOS (Intel): GooseRelayVPN-client-vX.Y.Z-darwin-amd64.tar.gz
   • macOS (M1/M2/M3): GooseRelayVPN-client-vX.Y.Z-darwin-arm64.tar.gz
   • Linux: GooseRelayVPN-client-vX.Y.Z-linux-amd64.tar.gz
   • Android / Termux (arm64): GooseRelayVPN-client-vX.Y.Z-android-arm64.tar.gz

3. For the server, SSH into your VPS and download the binary for your server OS:

   • Linux (most common):

     wget https://github.com/kianmhz/GooseRelayVPN/releases/latest/download/GooseRelayVPN-server-vX.Y.Z-linux-amd64.tar.gz
     tar -xzf GooseRelayVPN-server-vX.Y.Z-linux-amd64.tar.gz
     

   • Windows Server: download GooseRelayVPN-server-vX.Y.Z-windows-amd64.zip from the Releases page and extract it to a folder such as C:\goose-relay\. See the Windows Server (NSSM) subsection of Step 8 below for service setup.

   (Replace vX.Y.Z with the latest version number from the Releases page.)

If the Releases page doesn't open, you can download directly using these links (replace vX.Y.Z with the latest version):

• Client — Windows: https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-client-vX.Y.Z-windows-amd64.zip
• Client — macOS (Apple Silicon): https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-client-vX.Y.Z-darwin-arm64.tar.gz
• Client — macOS (Intel): https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-client-vX.Y.Z-darwin-amd64.tar.gz
• Client — Linux: https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-client-vX.Y.Z-linux-amd64.tar.gz
• Client — Android/Termux: https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-client-vX.Y.Z-android-arm64.tar.gz
• Server — Linux: https://github.com/Kianmhz/GooseRelayVPN/releases/download/vX.Y.Z/GooseRelayVPN-server-vX.Y.Z-linux-amd64.tar.gz

Option B — Build from source (Go 1.22+) — not recommended, may be unstable:

git clone https://github.com/kianmhz/GooseRelayVPN.git
cd GooseRelayVPN
go build -o goose-client ./cmd/client
go build -o goose-server ./cmd/server

Option C — Run only the server with Docker (GHCR):

If you prefer containers on your VPS, you can run goose-server directly from GHCR:

docker pull ghcr.io/kianmhz/gooserelayvpn-server:latest

Step 3: Generate a secret key

Run this once:

openssl rand -hex 32

Copy the 64-character string it prints. You'll use the same value in both the client and server configs. Keep it secret — anyone with this key can use your tunnel.

Step 4: Configure

Copy the example configs:

cp client_config.example.json client_config.json
cp server_config.example.json server_config.json

Open both files and paste your key into the tunnel_key field. Leave script_keys empty for now.

client_config.json:

{
  "socks_host":  "127.0.0.1",
  "socks_port":  1080,
  "google_host": "216.239.38.120",
  "sni":         "www.google.com",
  "script_keys": ["PASTE_DEPLOYMENT_ID"],
  "tunnel_key":  "PASTE_OUTPUT_OF_GEN_KEY"
}

server_config.json:

{
  "server_host": "0.0.0.0",
  "server_port": 8443,
  "tunnel_key":  "SAME_VALUE_AS_CLIENT"
}

Step 5: Set up the Google Apps Script

This is the free Google-side piece that hides your traffic.

1. Go to Google Apps Script and sign in.
2. Click New project.
3. Delete the default code and paste everything from apps_script/Code.gs.
4. Change this line to your VPS IP and port:

   const RELAY_URLS = [
     'http://YOUR.VPS.IP:8443/tunnel',
   ];
   

   RELAY_URLS is an array so you can list multiple VPS exit servers — Code.gs tries them in order and only falls over to the next one on an error. For a single VPS, one entry is enough.
5. Click Deploy → New deployment → set type to Web app.
6. Set Execute as: Me and Who has access: Anyone.
7. Click Deploy. A dialog appears showing the Deployment ID. Copy that value and paste it into script_keys.
8. Paste that ID into script_keys in client_config.json.

⚠️ Every time you edit Code.gs you must create a new deployment (Deploy → New deployment) and update script_keys. Just saving the code is not enough.

Step 6: Open port 8443 on your VPS firewall

The server needs port 8443 to be reachable from the internet. On your VPS run:

sudo ufw allow 8443/tcp

Then verify it works from your own computer (replace with your real VPS IP):

curl http://YOUR.VPS.IP:8443/healthz

You should get JSON like { "ok": true, "version": "vX.Y.Z", "protocol": 1 } with HTTP 200. If curl times out or refuses, also check your cloud provider's firewall (called "Security Groups" on AWS/Hetzner, "Firewall Rules" on DigitalOcean/Vultr, etc.) and add an inbound rule for TCP port 8443.

Step 7: Start the server on your VPS

On your VPS, run the server binary:

Linux:

./goose-server -config server_config.json

Windows Server:

.\goose-server.exe -config server_config.json

You should see it print the listening address and the healthz/tunnel URLs. Leave this terminal open, or set up the systemd/NSSM service (Step 8) to keep it running after reboots.

Docker (GHCR image):

⚠️ Important: The container does not auto-generate server_config.json. You must create and edit server_config.json first (with your own tunnel_key), then start the container.

docker run -d \
  --name goose-server \
  --restart unless-stopped \
  -p 8443:8443 \
  -v $(pwd)/server_config.json:/app/server_config.json:ro \
  ghcr.io/kianmhz/gooserelayvpn-server:latest

Docker Compose (recommended for container setup):

cp server_config.example.json server_config.json
nano server_config.json
docker compose up -d

The repo includes docker-compose.yml. By default it uses ghcr.io/kianmhz/gooserelayvpn-server:latest, and you can override it with:

GOOSE_SERVER_IMAGE=ghcr.io/kianmhz/gooserelayvpn-server:vX.Y.Z docker compose up -d

Verify from your own computer:

curl http://YOUR.VPS.IP:8443/healthz

Step 8: Keep the server running after reboot

If you want the exit server to start automatically after a VPS reboot, set up a service for your VPS OS.

Linux (systemd)

Run on your VPS:

sudo nano /etc/systemd/system/goose-relay.service

Paste this (adjust the path if your binary is in a different location):

[Unit]
Description=GooseRelayVPN exit server
After=network.target

[Service]
Type=simple
WorkingDirectory=/root
ExecStart=/root/goose-server -config /root/server_config.json
Restart=always
RestartSec=3
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Then run:

sudo systemctl daemon-reload
sudo systemctl enable goose-relay
sudo systemctl start goose-relay
sudo systemctl status goose-relay --no-pager

Windows Server (NSSM)

Use NSSM (Non-Sucking Service Manager) to register goose-server as a Windows service. The goose-server.exe binary is a plain Go binary — no installer needed.

1. Open port 8443 in Windows Firewall (run as Administrator in Command Prompt):

netsh advfirewall firewall add rule name="GooseRelayVPN" protocol=TCP dir=in localport=8443 action=allow

Also add an inbound TCP/8443 rule in your cloud provider's firewall panel (Security Groups / Firewall Rules).

2. Download NSSM from https://nssm.cc/download, extract it, and note the path to nssm.exe (e.g. C:\nssm\win64\nssm.exe).

3. Register and start the service (run as Administrator):