eooce/node-ws: a four-protocol proxy that runs as plain Node.js, no kernel

The problem eooce/node-ws solves: a proxy with no kernel to install

Most proxy servers are system services. You install a binary, it binds a port, and it keeps running whether or not your application is alive. eooce/node-ws inverts that. The whole server is a Node.js program, index.js, started by npm start, and its only runtime dependencies are ws and axios. There is no kernel, no separate daemon, and no compiled artifact in the repository. That matters on shared hosting and on PaaS platforms where you cannot install a system service at all but you can run a Node.js application. The README frames the target audience explicitly: it is aimed at Node environments, and the linked web-hosting.md guide is written for DirectAdmin panels that expose a Node.js App feature. The repository description goes further and lists four protocols (vless, trojan, shadowsocks and vmess), while the README body describes two (vless and trojan). That gap is the first thing to resolve before you commit to a deployment.

How the ws library carries vless and trojan traffic

The design leans on the ws package, which the package.json pins at ^8.14.2. A WebSocket connection is an HTTP upgrade, so the process can accept proxy traffic on the same port it uses for its own HTTP endpoints, and it can sit behind a reverse proxy or a CDN that already terminates TLS. The README's Cloudflare Workers example shows the intended topology: a Worker receives the request, rewrites url.hostname to a random entry from a list of disguise domains, and forwards it. That is a CDN in front of the Node process, not a replacement for it. The subscription endpoint is served by the same process, at a path controlled by SUB_PATH, which defaults to sub. So one Node process answers three kinds of request: the WebSocket upgrade that carries proxy traffic, the subscription path, and whatever else the host routes to it. The README does not document how the four protocols are multiplexed on that single WebSocket, and index.js is not reproduced in the repository listing, so the multiplexing scheme is not something this article can describe.

Installing eooce/node-ws on a Node host and reading your first subscription

The repository gives two install routes. On a DirectAdmin-style panel with the Node.js App feature, the README points at web-hosting.md rather than repeating the steps. Anywhere else, the Dockerfile is the concrete path: it is based on node:20-alpine3.20, copies index.js and package.json into /tmp, exposes port 3000, installs bash, openssl and curl, runs npm install, and starts with node index.js. Build the image and run it with the domain your host assigned. The DOMAIN variable is the only one the README marks as required, and it must be the bare hostname with no https:// prefix.

FROM node:20-alpine3.20

WORKDIR /tmp

COPY index.js package.json ./

EXPOSE 3000

RUN apk update && apk add --no-cache bash openssl curl &&\
    chmod +x index.js &&\
    npm install

CMD ["node", "index.js"]

If you are not using Docker, the package.json defines the start script, so a plain Node host runs the same file after npm install. The engines field requires Node 14 or newer.

npm install
npm start

Once the process is up, the README says the node information is at domain/SUB_PATH, or domain:port/SUB_PATH when the port is non-standard. With SUB_PATH left at its default, that URL is domain/sub, and opening it should return the subscription content for the node.

The environment variables that decide whether it boots correctly

Six variables are documented in the README table, and only one is required. UUID defaults to 5efabea4-f6d4-91fd-b8f0-17e004c89c60, and the README warns that you must change it if you have enabled Nezha v1. PORT defaults to 3000. NAME is a node-name prefix, shown in the README as Glitch. SUB_PATH defaults to sub and controls the subscription URL. AUTO_ACCESS defaults to false; setting it to true turns on automatic keep-alive requests and, per the README, requires DOMAIN to be filled in as well. The Nezha variables are the fiddly part. NEZHA_SERVER takes host:port form for v1 and a bare host for v0. NEZHA_PORT exists only for v0. NEZHA_KEY holds the NZ_CLIENT_SECRET for v1 or the agent port for v0. Setting any of them incorrectly is the most likely reason a deployment starts but never appears in the panel.

Where eooce/node-ws is the wrong tool

The licence is the sharpest constraint. The project is GPL-3.0, and the README adds three clauses on top: keep the author's information and the licence, release modified versions under the same licence, and do not use the project or any part of it commercially without explicit authorisation. The README then defines commercial use broadly, including embedding it in software you sell, profiting from it indirectly through ads or a SaaS service, and using it as a business tool inside a company. That last clause reaches further than most people expect from a GPL project, and it is a restriction the GPL itself does not impose. If your use is commercial, the README directs you to [email protected] for authorisation. Separately, the protocol mismatch is a real limitation: the repository description names four protocols, but the README body, the deployment guide reference and the environment-variable table all describe a vless plus trojan setup. Anyone who needs shadowsocks or vmess has no documented configuration for it. The README also does not document rollback, health checks, or what happens when the process crashes under a supervisor that does not restart it.

eooce/node-ws compared with running a dedicated proxy binary

The obvious alternative is a standalone proxy server that runs as its own process, typically a compiled binary managed by systemd or an equivalent. The difference is not protocol support, it is where the boundary sits. A dedicated binary survives your application restarts, has its own logging and its own port, and does not share a process with your HTTP endpoints. eooce/node-ws puts everything in one Node process, which is what makes it deployable on hosts that forbid system services, and also what makes it fragile in a different way: if the Node process dies, the proxy, the subscription endpoint and any keep-alive behaviour die together. The trade is portability for isolation. On a host where you control the operating system, the dedicated binary is the more conventional choice. On a DirectAdmin panel or a PaaS with a Node.js runtime and nothing else, the Node process is the only option, and that is the case this project is built for. The README's Cloudflare Workers snippet is not an alternative to the proxy itself; it only rewrites the hostname in front of it.

Upgrade cost and what the release history suggests

The repository's last push was on 2026-08-07, and it is not archived. The release list is uneven: gows-latest is dated 2026-01-04, node-ws-binary 2025-12-04, and a release tagged main goes back to 2023-10-28. There is no versioned release train and no changelog in the repository, so upgrading means pulling the current index.js and comparing it yourself. The dependency surface is small (ws and axios), and the engines field requires Node 14 or newer, which is a low floor. The practical upgrade risk is that index.js is the whole application: a single file carrying the proxy logic, the subscription endpoint and the Nezha integration. The README even links an external JavaScript obfuscator, which implies the published file may not be readable source in every distribution. If you need to audit or patch behaviour, that is a problem. On licence implications, the GPL-3.0 grant plus the README's commercial restriction means the terms you are actually bound by are the README's, not the SPDX identifier alone; this is a description of what the files say, not legal advice.

Editorial conclusion

Adopt eooce/node-ws if you already have a Node.js host (a DirectAdmin panel with the Node.js App feature, a PaaS, or the bundled Docker image) and you want the proxy to live inside the Node process rather than as a system service. Do not adopt it if you need a documented install path for shadowsocks or vmess, if you want to run it commercially, or if you expect the README to match the repository description. Before deploying, verify three things: that the DOMAIN variable is set, that your host lets an inbound connection reach the port given by PORT (default 3000), and that the four-protocol claim in the repository description is actually true for the index.js you are about to run.

Frequently asked questions

Official sources

1. eooce/node-ws on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases