nodejs-argo: an Argo tunnel proxy for Node PaaS and game-hosting platforms

What nodejs-argo is for, and who it is not for

nodejs-argo builds an Argo tunnel and exposes it as a proxy node. The README describes it as aimed at Node-based PaaS platforms and game-hosting platforms, and says the node side only needs index.js and package.json uploaded, while PaaS platforms that require Docker also take the Dockerfile. The proxy side supports VLESS, VMess and Trojan, with direct protocols Socks5, Hysteria2 and Reality listed as optional. Nezha probe integration is optional and supports v0 or v1. There is also a subscription endpoint, so a client can pull the node configuration rather than copying it by hand.

The audience is narrow on purpose. If you have a shell on a VPS and root access, this is not the shortest path to a proxy: you would run the underlying core directly. nodejs-argo exists because some platforms give you a Node runtime and a port, not a root shell. That constraint shapes the whole project, including the reliance on a single index.js entry point.

The README is blunt about scope. A notice dated 2025-10-29 states the project is for personal use only and forbids commercial use, naming YouTube, Bilibili, TikTok and Facebook as examples, and forbids copying the code into a new repository for commercial purposes. It also asks users to follow local law and not to run it as a public proxy. That is a usage restriction, not a technical one, and it is the first thing to weigh before deployment.

How the Argo tunnel, subscription and Nezha probe fit together

The process starts an HTTP service on PORT, default 3000, and an Argo tunnel on ARGO_PORT, default 8001. The tunnel is what gives the node a reachable hostname. Two variables control it: ARGO_DOMAIN and ARGO_AUTH. According to the README, leaving both empty starts a temporary tunnel; filling them in uses a fixed tunnel. That single branch decides whether the node address survives a restart, so it matters more than any other setting here.

Client configuration is served over HTTP. The README gives two subscription forms: https://your-domain.com/sub on a standard port, and http://your-domain.com:port/sub when the port is non-standard. SUB_PATH defaults to sub, so the path segment is configurable. UPLOAD_URL is optional and points at a subscription merge service, which is how you would aggregate this node with others.

The Nezha integration is a reporting side channel, not part of the proxy path. You supply NEZHA_SERVER, NEZHA_PORT and NEZHA_KEY, and choose v0 or v1. The README notes a detail worth reading twice: when the Nezha port is one of 443, 8443, 2096, 2087, 2083 or 2053, TLS is enabled automatically. That is a hardcoded list, so a panel on any other port gets a plain connection.

Two more variables shape the node rather than the tunnel. CFIP defaults to www.visa.com.tw and CFPORT defaults to 443; these are the preferred address and port written into the node. NAME sets a node name prefix. The default UUID is 9afd1229-b893-40c1-84dd-51e7ce204913, which is public and shared by every deployment that never sets UUID. Change it.

Installing nodejs-argo and getting a first node running

The README's install path is the npm package, globally. Run one of the three package-manager commands; the project recommends the global npm install. After this, nodejs-argo is on your PATH.

npm install -g nodejs-argo

Running it with no arguments uses the defaults: HTTP on port 3000, Argo on 8001, a temporary tunnel, and the shared default UUID. For a first run that is enough to see the process start and print its log, since SHOW_LOG defaults to true.

nodejs-argo

npx works too and skips the global install. The README's example sets PORT inline, which is the quickest way to test a platform that assigns a specific port.

PORT=3000 npx nodejs-argo

For anything beyond a test, export the variables that define your node and tunnel. The README shows this form, including a merge-subscription URL, a project URL, a UUID of your own, and Nezha credentials. Use a UUID you generate, not the default.

export UPLOAD_URL="https://your-merge-sub-domain.com"
export PROJECT_URL="https://your-project-domain.com"
export PORT=3000
export UUID="your-uuid-here"
export NEZHA_SERVER="nz.your-domain.com:8008"
export NEZHA_KEY="your-nezha-key"

The README also states that a .env file can hold these values, though it does not print an example of the file contents. The npm module form is available as well: require('nodejs-argo') in CommonJS or a default import in ES modules, then call nodejsArgo.start().

const nodejsArgo = require('nodejs-argo');
nodejsArgo.start();

For a long-running deployment the README lists screen, tmux, PM2 and systemd. The systemd unit it prints sets Environment=ARGO_PORT=8080 and Environment=PORT=3000, runs /usr/bin/npx nodejs-argo, and restarts after 10 seconds. Note that ARGO_PORT differs from the 8001 default in that example.

Where nodejs-argo breaks or is the wrong tool

The most consequential failure mode is the temporary tunnel. If ARGO_DOMAIN and ARGO_AUTH are both empty, the README says a temporary tunnel is used. Temporary addresses are not stable, so a client subscription pointing at one will need to be refreshed whenever the address changes. If your clients cannot tolerate that, you must supply a fixed tunnel, which means owning a domain and an Argo credential. The README does not document a rollback or migration path between the two modes.

The default UUID is the second trap. 9afd1229-b893-40c1-84dd-51e7ce204913 ships as the default in the environment table. Every deployment that does not override it shares the same node identity. That is a configuration mistake waiting to happen, and the README presents it as a default rather than warning against it.

The repository is thin. The top-level entries are .github/, Dockerfile, README.md, index.html, index.js and package.json, and package.json lists a single dependency, axios, with the version pinned to latest. There is no lockfile in the listing, so an install can pull a different axios than the one the author ran. The package.json also looks unfinished: the name is nodejs, the description is "Thsi is a node project", and the version is the string "1,0,0" with commas, which is not a valid semver value. None of this stops it running, but it tells you how much packaging care went into the published artifact, and it makes version pinning harder than it should be.

Finally, this is a single-file Node process. It is not a hardened proxy server, and the README's own notice forbids using it as a public proxy. If you need a multi-user proxy with access control, this is the wrong tool.

How it differs from running Xray or sing-box directly

The obvious alternative is running the underlying proxy core yourself, Xray or sing-box, on a VPS with systemd. The difference is not the protocol support; the cores do VLESS, VMess and Trojan natively, and nodejs-argo is a wrapper around that kind of engine. The difference is the deployment target and what you get for free.

With a core installed directly, you write the inbound and outbound configuration, obtain a certificate or a tunnel, and wire up your own subscription file. You get full control over routing rules, transport options and user management, and you are not limited by a single index.js. You also get a process that is maintained by its own upstream, with release notes and versioned artifacts.

nodejs-argo trades that control for a Node entry point that fits platforms where you cannot install a system service. It generates the node configuration, serves the subscription at /sub, and optionally reports to Nezha. The cost is that protocol options beyond the documented set are not exposed as configuration; you get the variables in the table and nothing else. If your platform gives you a Dockerfile or a Node runtime, nodejs-argo is less work. If you have root on a VPS, the core alone is the better fit, and the extra layer only adds a dependency on a package whose version string is not valid semver.

Maintenance, updates and what the licence actually says

The repository is not archived, and the last push was on 2026-09-07, which is recent enough that the code has moved this month. There are no retrieved releases, so there is no changelog to read before upgrading; you are tracking a branch, not a tagged version. The README's update instructions are two commands: npm update -g nodejs-argo, or uninstall and reinstall. Neither pins a version, and with axios declared as latest, an update can change transitive behaviour without any signal in the project itself.

Licensing is the part to read carefully, and this is not legal advice. package.json declares "license": "MIT". The README states that the project changed its open source licence on 2025-10-29 and now carries specific requirements: personal use only, no commercial use, no copying the code into a new repository for commercial purposes, and no abuse as a public proxy. Those two statements do not agree. The repository does not include a LICENSE file in its top-level listing, so there is no third document to break the tie. If you intend to use this at work, or in anything that earns money, resolve that conflict before you deploy, and treat the README's restrictions as the author's stated intent.

The practical maintenance cost is the wrapper itself. You are updating a package that runs a core, and when the core's behaviour changes, the wrapper has to follow. With no releases and no LICENSE file, you are relying on the README and the commit history to know what changed.

Editorial conclusion

Adopt nodejs-argo if you already run Node on a PaaS or game-hosting platform, need a tunnel node with a subscription URL, and accept the personal-use-only terms in the README. Do not adopt it for a commercial service: the project's own notice forbids commercial use, including streaming platforms, and forbids copying the code into a new repository for commercial purposes. Before deploying, verify the licence terms yourself, since package.json declares MIT while the README states the licence changed on 2025-10-29 with additional restrictions, and confirm whether you need a fixed tunnel (ARGO_DOMAIN plus ARGO_AUTH) or will accept the temporary tunnel that starts when both are empty.

Frequently asked questions

Official sources

1. eooce/nodejs-argo on GitHub
2. Issues
3. Project website
4. README