explaingit

nikvpn-iran/nikvpn-mobile-codespace

★ 14ShellAudience · vibe coderComplexity · 2/5ActiveLicenseSetup · easy

TLDR

Turn a free GitHub Codespace into a personal VPN for your phone by running Xray and scanning a QR code to connect.

Mindmap

mindmap
  root((repo))
    What it does
      GitHub Codespace VPN
      Xray proxy engine
      Mobile phone tunnel
    How to use
      Scan QR code
      Pick transport mode
      Connect via client
    VPN options
      VLESS xHTTP port 443
      VLESS XTLS Vision port 8443
    Tech stack
      Xray proxy
      Shell scripts
      Docker container
    Supported clients
      Nekoray
      V2rayNG
      Clash Shadowrocket

Things people build with this

USE CASE 1

Set up a personal VPN tunnel on a free GitHub Codespace and connect your phone to it in minutes.

USE CASE 2

Route mobile traffic through a cloud-hosted proxy to bypass network restrictions or improve privacy.

USE CASE 3

Test Xray configurations and VPN transport modes (xHTTP vs XTLS-RPRX-Vision) without buying a server.

Tech stack

XrayShellDockerGitHub Codespacestmux

Getting it running

Difficulty · easy Time to first run · 5min

Requires making the Codespace port public in GitHub settings; Xray installs automatically via setup script.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

In plain English

This project, written in Farsi for Iranian users, turns a GitHub Codespace into a small personal VPN that you can connect to from a phone. The idea is that GitHub Codespaces gives you a free virtual Linux machine in the cloud, and this repository contains the scripts and config files needed to install Xray on that machine and expose two VPN configurations to your mobile device. When you create a Codespace from the repository, a setup script runs automatically. It downloads and installs Xray, the popular open-source proxy engine, and then starts an interactive terminal menu. On first run the menu asks you which of two configurations you want to use. Option one is VLESS with xHTTP transport on port 443, presented as the safer default. Option two is VLESS with XTLS-RPRX-Vision flow on port 8443, presented as faster and harder to detect. Once you pick one, the script prints a QR code in the terminal that contains the full connection link. From your phone, you scan that QR code with the camera, then open a compatible VPN client like Nekoray, V2rayNG, Clash, Shadowrocket, or Stash, and the configuration is added automatically. After that you tap connect and your phone routes traffic through the Codespace. The README includes example vless:// links showing the UUID, server hostname under github.dev, the SNI, and the transport settings. The terminal menu has commands beyond the initial setup. You can show the current config links, regenerate larger QR codes for easier scanning, tail the Xray log at /tmp/xray.log, restart Xray after a config change, check service health, and attach to a tmux session for advanced control. The repository layout is small: a Dockerfile, devcontainer.json, setup.sh, start.sh, menu.sh, show-configs.sh, generate-qr.sh, and two JSON config files for the two transport modes. The README also includes troubleshooting tips for Xray not starting, missing qrencode, or failed connections, with reminders to make the Codespace port public. It is released under the MIT license.

Copy-paste prompts

Prompt 1
How do I set up a GitHub Codespace VPN using this repo? Walk me through the QR code scanning process.
Prompt 2
What's the difference between the VLESS xHTTP and VLESS XTLS-RPRX-Vision transport modes in this VPN setup?
Prompt 3
I scanned the QR code but my phone VPN client won't connect. What troubleshooting steps should I try?
Prompt 4
Show me how to regenerate a larger QR code and restart the Xray service from the terminal menu.
Prompt 5
How do I check the Xray logs to debug connection issues in this Codespace VPN?
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.