g2ray: a V2Ray proxy that runs inside GitHub Codespaces

What g2ray actually solves, and for whom

Running a proxy normally means renting a host, hardening it, and keeping it alive. g2ray removes the host-rental step by putting the proxy inside a GitHub Codespace, the browser-based development environment GitHub provides. You fork the repository, start a codespace on the main branch, and the setup prints a connection string that a client such as v2rayNG or Nekobox can consume. That is the whole product surface described in the README: no server to provision, no domain, no TLS certificate to buy.

The audience is narrow and clearly stated. The README calls the project "strictly experimental and intended for educational and research purposes only." It is for someone who wants to see how a proxy endpoint is assembled and used, or who wants a temporary egress point, and who already has a GitHub account. It is not presented as infrastructure for production traffic, and nothing in the README suggests the author wants it treated that way.

How the Codespace becomes a proxy endpoint

The mechanism is a build step, not a running service you configure by hand. The repository's top level contains a .devcontainer directory, which is the hook GitHub Codespaces uses to construct the environment. When you create a codespace on main, the devcontainer definition is applied, the environment builds, and initialization runs. The README tells you to wait a few minutes for that to finish, then look at the terminal, where the connection string appears once setup is complete.

Data then flows from your client to the codespace and out to the destination through GitHub's network. The client side is standard: you paste the printed link into v2rayNG, Nekobox, or another compatible client. There is no control panel, no API, and no documented way to change the proxy parameters from the repository. The README also does not document what happens on a rebuild, whether the string survives a restart, or how to rotate credentials. Those gaps matter more than the happy path, because a codespace is an ephemeral environment and the README treats it as one.

Setting up g2ray: fork, codespace, paste the string

There is no package to install and no binary to download. The README's Quick Start is a four-step sequence performed entirely in the browser. First, fork the repository to your own GitHub account. Second, open the Codespaces tab under the Code button on your fork. Third, create a new codespace on the main branch. Fourth, wait for the environment to build and initialize.

The README does not give a command-line equivalent, and no install command, configuration file or environment variable appears anywhere in the repository files, so the browser flow above is the whole setup. After the environment is ready, the README says your connection string will appear in the terminal. That string is the artifact you carry to the client. The README gives this instruction: paste the link into any compatible client, naming v2rayNG and Nekobox as examples.

One operational step belongs with the setup. The README warns that you should stop your codespace when you are not actively using it, because an idle codespace consumes the same quota as a busy one.

The 120 core-hour ceiling is the real constraint

The README is unusually direct about the limit: GitHub Codespaces provides 120 core-hours per month on the free tier, and because this configuration uses 2 cores, that works out to roughly 60 hours of runtime per month. Two hours a day, in other words, and only if you stop the environment every time you finish. Leave a codespace running overnight and the monthly budget disappears faster than the calendar suggests.

This is not a soft limit you can engineer around inside the project. It is a property of the host. A proxy endpoint that stops existing when the quota runs out is a different class of tool from a VPS, and anyone comparing the two should compare them on that axis first. The README does not document what happens when the quota is exhausted, whether the codespace is suspended or deleted, or how long the connection string remains valid after a stop. Those are the questions to answer before depending on it for anything.

Networks that block GitHub, and other reasons it fails

The README states that g2ray works on most networks that are not aggressively blocking GitHub infrastructure. That sentence is doing a lot of work. The proxy depends on reaching GitHub to exist at all, so a network that interferes with GitHub access is a network where this approach has no path to working. The suggested mitigation is to create the codespace in a different datacenter if the default region does not work for you, which changes the egress location but not the dependency.

A second failure mode is quieter: the setup is experimental, and the README offers no troubleshooting section, no log locations, and no documented recovery if the build does not complete or the string never prints. You are left reading the terminal output yourself. A third is legal and organisational rather than technical. The disclaimer places responsibility on the user to comply with applicable local laws and regulations, and the README explicitly claims the project does not violate GitHub's Terms of Service because it uses Codespaces as an officially provided feature in its intended manner. That is the author's position, stated in the README, not a guarantee that applies to your use case or your jurisdiction.

Where a plain VPS differs from a Codespace proxy

The obvious alternative is renting a small VPS and running a proxy server on it. The difference is not performance, it is ownership of the lifecycle. On a VPS you control when the process starts and stops, you keep the same IP until you release it, and the endpoint keeps answering whether or not you are at your desk. With g2ray the endpoint is tied to a codespace that you are told to stop when idle, and the runtime budget resets monthly rather than being billed by usage.

The trade is cost and setup effort against continuity. A VPS costs money every month and requires you to manage an operating system. g2ray costs nothing on the free tier and requires no server administration, but it inherits GitHub's quota, GitHub's network position, and the ephemeral nature of a development environment. If your need is a persistent endpoint, the Codespace model is structurally the wrong shape. If your need is a temporary one you can spin up from a browser, the trade goes the other way.

Maintenance, licence, and what the repository metadata says

The repository is not archived, and the last push was on 2026-05-10. With no releases retrieved, there is no version history to reason about and no upgrade path documented in the README. Upgrades in practice come from re-forking or syncing your fork and rebuilding the codespace, which means the maintenance cost is mostly the cost of watching upstream and rebuilding. The README does not describe a rollback procedure, so treat a rebuild as the recovery mechanism.

On licensing there is a discrepancy worth noting. The README ends with a License section stating MIT and pointing at the LICENSE file, while the repository metadata reports the licence as NOASSERTION, meaning GitHub could not classify it automatically. The LICENSE file is the authoritative text; read it in your fork rather than relying on the metadata badge. Nothing here is legal advice, and if you plan to redistribute or build on the code, the file itself is what you need to read.

Editorial conclusion

g2ray fits someone experimenting with a self-hosted proxy who already has a GitHub account and does not want to run a server: fork the repo, open a Codespace on main, and take the connection string from the terminal. It is the wrong tool if you need an endpoint that is always up, if you depend on a network that blocks GitHub, or if a 60-hour monthly ceiling on the free tier is too tight. Before relying on it, verify that the Codespace actually builds in your account, check the datacenter region if the default one fails, and read the LICENSE file, because the repository metadata reports NOASSERTION while the README states MIT.

Frequently asked questions

Official sources

1. amircloner/g2ray on GitHub
2. Issues
3. README