explaingit

nikvpn-iran/nikvpn-mobile-codespace

Analysis updated 2026-06-24

★ 13ShellAudience · generalComplexity · 2/5LicenseSetup · moderate

TLDR

Turns a free GitHub Codespace into a personal VPN by installing Xray and exposing VLESS configs as QR codes for mobile clients.

Mindmap

mindmap
  root((nikvpn-mobile-codespace))
    Inputs
      GitHub Codespace
      User choice of transport
    Outputs
      QR code
      VLESS config link
      Xray service
    Use Cases
      Personal mobile VPN
      Bypass restrictions in Iran
      Test Xray transports
    Tech Stack
      Shell
      Xray
      Docker
      Devcontainer
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

Spin up a personal VPN on a free GitHub Codespace and connect from a phone

USE CASE 2

Test VLESS xHTTP vs XTLS-RPRX-Vision transports side by side

USE CASE 3

Generate QR codes for V2rayNG, Nekoray, or Shadowrocket from the terminal

USE CASE 4

Tail Xray logs and restart the service after editing transport configs

What is it built with?

ShellXrayDockerDevcontainerqrencodetmux

How does it compare?

nikvpn-iran/nikvpn-mobile-codespaceadukecoins/codewatchfrichxi/zanai-writing-skill
Stars131313
LanguageShellShellShell
Setup difficultymoderatemoderateeasy
Complexity2/52/52/5
Audiencegeneraldeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · moderate Time to first run · 30min

You must create a Codespace from this repo and make the forwarded port public before the QR code link will connect.

MIT license, free to use, modify, and distribute with attribution.

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
Walk me through opening this repo as a GitHub Codespace and connecting V2rayNG to the printed QR code
Prompt 2
Compare the VLESS xHTTP config on port 443 with the XTLS-RPRX-Vision config on port 8443 in this repo
Prompt 3
Show me how setup.sh, start.sh, and menu.sh fit together when the Codespace boots
Prompt 4
Modify the menu so it always regenerates a larger QR code without asking
Prompt 5
Add a third transport option to the menu and write the matching JSON config file

Frequently asked questions

What is nikvpn-mobile-codespace?

Turns a free GitHub Codespace into a personal VPN by installing Xray and exposing VLESS configs as QR codes for mobile clients.

What language is nikvpn-mobile-codespace written in?

Mainly Shell. The stack also includes Shell, Xray, Docker.

What license does nikvpn-mobile-codespace use?

MIT license, free to use, modify, and distribute with attribution.

How hard is nikvpn-mobile-codespace to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is nikvpn-mobile-codespace for?

Mainly general.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Verify against the repo before relying on details.

Alternatives & similar repos