🛰️ GCP SSH Relay

Reach your phones (Termux / Ubuntu-in-Termux) from anywhere through a free-tier Google Cloud VM — no app on the computer you connect from, no paid services, no router config.

Create account Login Download the docs artifact

How it works

   Your PC                 GCP VM (tyrostir.duckdns.org)              Phone (Termux)
 ssh -p PORT  ───────────►  tyrostir.duckdns.org:PORT  ──reverse──►  localhost:8021/8022 (sshd)
                            ▲  reverse tunnel dialed OUT by the phone  ▲

Each phone dials out to the VM and asks it to reverse-forward a public port back to the phone's local sshd. Your PC connects to tyrostir.duckdns.org:PORT. One VM serves many phones — one port per phone (2222–2240).

Accounts & verification

This portal (Django + DRF + allauth) lets you:

• Log in with username, email, or mobile number + password.
• Verify email and mobile via a TOTP code that is printed to the server console and appended to an SSH-readable file (otp_codes/email_otps.txt, otp_codes/mobile_otps.txt).
• Reset a forgotten password with a TOTP code the same way.

Read a code over SSH, e.g.: tail -n5 ~/gcprelay/otp_codes/email_otps.txt

REST API (DRF)

POST gcprelay/api/register/                {username,email,mobile_number,password}
POST gcprelay/api/login/                   {identifier,password} -> token
POST gcprelay/api/otp/email/request/       {identifier}
POST gcprelay/api/otp/email/verify/        {identifier,code}
POST gcprelay/api/otp/mobile/request/      {identifier}
POST gcprelay/api/otp/mobile/verify/       {identifier,code}
POST gcprelay/api/password/reset/request/  {identifier}
POST gcprelay/api/password/reset/confirm/  {identifier,code,new_password}

The scripts

Every script is downloadable and documented below with a usage example.

Phone setup — Termux-native — gcp-phone-setup.sh

One-shot onboarding for a fresh phone (no Ubuntu). Installs a key-only Termux sshd and a self-healing reverse tunnel to the VM.

bash gcp-phone-setup.sh --port 2223 \
     --vm-key ./google_compute_engine \
     --pc-pubkey ./pc-access-key.pub

Download gcp-phone-setup.sh

Phone teardown — Termux-native — gcp-phone-teardown.sh

Stops the relay + sshd on the phone and releases the VM port immediately so the next phone can reuse it.

bash gcp-phone-teardown.sh --port 2223 [--disable-autostart]

Download gcp-phone-teardown.sh

Phone setup — Ubuntu-in-Termux — gcp-phone-setup-ubuntu.sh

Same idea for a phone that already runs Ubuntu (proot-distro or start-ubuntu22). Tunnels the Ubuntu sshd on port 8021.

bash gcp-phone-setup-ubuntu.sh --port 2224 \
     --vm-key ./google_compute_engine \
     --pc-pubkey ./pc-access-key.pub

Download gcp-phone-setup-ubuntu.sh

Phone teardown — Ubuntu-in-Termux — gcp-phone-teardown-ubuntu.sh

Termux-side teardown for the Ubuntu flavour; frees the VM port and can decommission autostart.

bash gcp-phone-teardown-ubuntu.sh --port 2224 [--keep-sshd]

Download gcp-phone-teardown-ubuntu.sh

The reverse-tunnel loop — gcp_relay.sh

The core keep-alive loop each phone runs. Singleton per port via flock; reconnects automatically if the tunnel drops.

bash gcp_relay.sh [VM_IP] [PORT]

Download gcp_relay.sh

Provision the GCP relay VM — provision-vm.sh

Autonomous VM creator: gcloud sign-in, project, free-tier e2-micro, firewall range, sshd tweaks, and the list-phones helper.

bash provision-vm.sh --project personal-projects-hub \
     --pc-pubkey ./pc-access-key.pub

Download provision-vm.sh

Deploy this portal on the VM — deploy-site.sh

Sets up the Django site behind gunicorn + nginx at http://<vm-ip>/gcprelay (venv, migrate, collectstatic, systemd).

sudo bash deploy-site.sh --repo <git-url> --host <vm-ip>

Download deploy-site.sh

Full phone-relay guide

Architecture, cost, onboarding, troubleshooting, and security details: PHONE-RELAY.md.