shadowsocks/v2ray-plugin: a SIP003 plugin that wraps Shadowsocks in WebSocket, TLS or QUIC

What problem v2ray-plugin solves, and who it is for

Plain Shadowsocks traffic has a recognisable shape on the wire. v2ray-plugin changes that shape. It is a SIP003 plugin, which means it is not a proxy by itself: it is loaded by a Shadowsocks client or server and given the stream to carry. The README calls it "yet another SIP003 plugin for shadowsocks, based on v2ray", and the repository is a thin Go program around v2fly/v2ray-core rather than a fork of it. The audience is narrow and specific. You already have a working Shadowsocks deployment, you control both endpoints, and you want the connection to look like ordinary web traffic or like QUIC. If any of those three conditions is false, the plugin adds a moving part without solving anything.

How the plugin carries a Shadowsocks stream

The plugin process is started by the Shadowsocks binary and speaks SIP003 over stdin and stdout: the parent hands it the server host and port, and the plugin opens the real network connection. On the server side the plugin listens and accepts; on the client side it dials. Everything above that is v2ray-core's transport layer. Three modes are documented. The default is WebSocket over plain HTTP, which the README describes as providing "a moderate (but lightweight) traffic obfuscation" and warns cautious users to avoid. Adding tls wraps the WebSocket in TLS, and mode=quic switches the transport to QUIC. The mode and the TLS host are set in the --plugin-opts string, so the client and server must agree on both. The repository layout reflects this: args.go parses the option string, main.go wires the process to v2ray-core, and utils.go holds the shared helpers. The go.mod file pins github.com/v2fly/v2ray-core/v5, so the transports come from upstream rather than from code in this repository.

Installing v2ray-plugin and running a first TLS tunnel

There is no package manager step in the README. The documented build is a single Go command, and the README points at CircleCI artifacts as the nightly alternative. The go.mod file requires Go 1.22.0 with toolchain go1.23.2, so a recent Go installation is needed.

go build

That produces a v2ray-plugin binary in the working directory. The README does not say where to install it; it only says the plugin is passed to the Shadowsocks binaries by name, so the binary has to be discoverable on PATH, or given as a path, on both machines.

For the TLS mode, the README's own example starts the server on port 443. Note that the option string is a semicolon-separated list, and the host value is the domain the certificate was issued for.

ss-server -c config.json -p 443 --plugin v2ray-plugin --plugin-opts "server;tls;host=mydomain.me"

The matching client command drops server and keeps tls and host. If the two strings disagree, the handshake fails before Shadowsocks ever sees a byte.

ss-local -c config.json -p 443 --plugin v2ray-plugin --plugin-opts "tls;host=mydomain.me"

Certificates are the part most likely to trip you up. The README states that v2ray-plugin looks for certificates signed by acme.sh by default, and gives the CloudFlare DNS example below. Other DNS providers are documented at acme.sh itself.

curl https://get.acme.sh | sh
~/.acme.sh/acme.sh --issue --dns dns_cf -d mydomain.me

If you already have a certificate elsewhere, the cert and key options point at the files instead, and certRaw accepts the PEM body directly, without the BEGIN and END lines and without line breaks.

Where v2ray-plugin is the wrong tool

The plugin cannot be used on its own. There is no standalone server mode, no subscription handling and no user management: without a Shadowsocks implementation that speaks SIP003 on both ends, the binary does nothing useful. That rules it out for anyone looking for a complete proxy service rather than a transport for one. The HTTP mode is weaker than it sounds. The README is explicit that HTTP only provides moderate obfuscation and that cautious users should refrain from using it, so treating the default mode as a censorship countermeasure overstates it. The QUIC mode is documented in three lines, and the README does not describe its failure behaviour, its interaction with middleboxes that drop UDP, or how it behaves when the certificate is missing. The release history is another practical constraint: the newest release listed is v1.3.2 from 2022-09-08, while the last push to the repository was on 2026-07-09. The code has moved since the last tagged release, so anyone building from a tag is getting something older than master. Finally, the README does not document rollback, so there is no documented way back if a transport change breaks a live deployment.

How this differs from running v2ray-core directly

The obvious alternative is to configure v2ray-core itself, since this plugin is built on it. The difference is who owns the connection. A direct v2ray deployment defines inbound and outbound protocols in a JSON or JSONC configuration file and runs as its own daemon; the plugin instead reads its options from a single --plugin-opts string and is spawned by the Shadowsocks process. That makes the plugin easier to bolt onto an existing Shadowsocks setup, and harder to use for anything beyond a single transport between two endpoints. If you need routing rules, multiple inbounds or per-user policy, the configuration surface of v2ray-core is where that lives, and the plugin does not expose it. If you only need to change how one Shadowsocks stream looks on the wire, the plugin is the smaller change.

Maintenance, upgrade cost and licence

The repository is not archived, and the last push was on 2026-07-09, so the codebase is not abandoned. It is also not on a release cadence: the three releases listed are v1.3.0 from 2020-02-05, v1.3.1 from 2020-06-01 and v1.3.2 from 2022-09-08. Anyone who tracks tags rather than master is running code several years behind the last commit, and the go.mod file shows why that matters: the dependency on github.com/v2fly/v2ray-core/v5 is at v5.22.0, and transport behaviour lives there. Upgrading the plugin therefore means rebuilding against a current v2ray-core, which is a rebuild rather than a configuration change. The licence is MIT, which permits commercial and closed-source use; the LICENSE file is at the repository root. That is a statement about the licence text, not legal advice, and the dependencies carry their own licences.

Editorial conclusion

Adopt v2ray-plugin if you already run Shadowsocks and need its stream to look like WebSocket, TLS or QUIC traffic on a port you control. Do not adopt it as a standalone proxy: it has no server of its own and only works when a Shadowsocks implementation loads it as a SIP003 plugin. Before deploying, verify the plugin is on PATH on both sides, that the server and client --plugin-opts strings match, and that a certificate is reachable, either through acme.sh or through the cert and key options.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. shadowsocks/v2ray-plugin on GitHub