Roxxie node agent

roxxie-transports-node turns a Linux, macOS, or Windows computer into a Roxxie exit node. The agent makes one outbound WSS control connection to the central tracker. It never exposes an HTTP server, never carries proxy traffic over that WSS connection, and does not need a domain, TLS certificate, public listener, or router port-forward.

browser ── WSS/HTTPS signaling ── tracker
   │                                 │
   └──────── direct WebRTC ───────── node ── HTTP(S) / site WS(S)

The tracker validates a new node through a real WebRTC proxy session and approves it automatically only when the complete proxied request succeeds. Approved nodes are continuously health-checked and can move between online and unhealthy without another admission step. Because Roxxie deliberately has no TURN relay, some symmetric-NAT or very restrictive firewall combinations cannot connect. The browser responds by trying another approved node.

Requirements

• Node.js 18 or newer. npm may only warn about the declared engine range unless engine-strict is enabled; doctor and the update self-check reject older runtimes. Release validation should cover Node 18, 20, 22, 24, and the latest stable release before publishing. Reinstall the package after changing Node major versions so its native WebRTC addon matches the active runtime. Note that Node 18 reached end of life in April 2025 and no longer receives security updates; prefer a maintained release where you have the choice.
• A platform supported by @roamhq/wrtc: Linux x64/arm64, macOS x64/arm64, or Windows x64. Native WebRTC availability ultimately depends on that package.
• Outbound HTTPS/WSS to the tracker, TCP to target-site HTTP(S)/WS(S) ports, HTTPS to Cloudflare DoH, the npm registry/release-tarball hosts, and WebRTC/STUN UDP access. No fixed inbound service port or certificate is required.
• Either an unprivileged operator account or root/Administrator. A root install uses a hardened machine-wide system service and a protected system configuration; an unprivileged Unix install uses the existing per-user service. On Linux, enabling systemd user lingering may prompt for administrator authorization for the latter.
• A writable npm global prefix for signed self-updates. A root installation may use its normal system prefix; a non-root installation should use a user-owned prefix.

Install and register

After publication:

# Unprivileged Linux/macOS example when npm's current prefix is root-owned:
npm config set prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
npm install --global [email protected]

# A root/Administrator global install is also supported:
sudo npm install --global [email protected]

That single direct npm global install creates the default configuration when it does not exist, installs and starts the native service, and lets the service submit its UUID for tracker validation and automatic approval. A root install creates the corresponding machine-wide service. It does not wait for tracker reachability: the supervised agent keeps retrying after an outage. Reinstalling or updating the package preserves the existing UUID, secret, configuration, and service.

The automatic hook runs only for a direct, top-level npm global install. Local, workspace, transitive, pnpm/yarn, and signed-updater installs do not bootstrap a node. npm's --ignore-scripts also disables it. To opt out for a custom setup:

ROXXIE_NODE_AUTO_INSTALL=0 npm install --global [email protected]
roxxie-node setup --name "Community node" --install-service

Before removing the npm package, explicitly remove its native service; current npm releases do not run package uninstall lifecycle hooks. This retains the configuration and node identity for a future reinstall:

roxxie-node service uninstall
npm uninstall --global roxxie-transports-node

If setup already created a configuration but native service installation failed, fix the reported prerequisite and run roxxie-node service install; do not use --force. The explicit setup command defaults to the production tracker at https://100.58.76.81/. Pass --tracker https://IP_ADDRESS/ to select another tracker; the URL must use its certificate-covered direct IP address. setup converts the HTTPS origin to the node-control WSS endpoint, creates a random UUID v4 and a random 32-byte bootstrap secret, stores both in a mode-0600 configuration where supported, and attempts to fetch the tracker's Ed25519 release key over validated HTTPS. No administrator-issued token is required. If the key is unavailable, proxy operation continues and the daily updater retries safely; signed updates remain disabled until the key is provisioned. On Windows the automatic installer protects %APPDATA%\Roxxie with a non-inherited DACL for only the current operator and Local System before it writes the identity.

The first successful connection submits the fresh UUID and proves possession of its bootstrap secret. The tracker performs a real client-like WebRTC, Adrift, and proxied HTTPS test. A pass atomically rotates the credential to an approved secret; the node is not advertised until it acknowledges that secret. Failure, explicit rejection, and revocation erase reusable credentials and are terminal until the operator registers a new identity with setup --force.

Default configuration locations are:

• Linux: ~/.config/roxxie/node.json
• macOS: ~/Library/Application Support/Roxxie/node.json
• Windows: %APPDATA%\Roxxie\node.json

Root defaults are /var/lib/roxxie-node/node.json on Linux and /Library/Application Support/Roxxie/node.json on macOS.

Use --config PATH or ROXXIE_NODE_CONFIG to select another path.

Operate

roxxie-node doctor
roxxie-node service status
roxxie-node service install
roxxie-node service uninstall
roxxie-node serve                 # foreground mode
roxxie-node update                # signed update check now

An unprivileged Linux install uses a systemd user unit with lingering and an unprivileged macOS install uses a LaunchAgent. Root installs use a hardened system-level systemd unit or LaunchDaemon. Windows uses a Scheduled Task. User jobs start when the operator logs in after a reboot; system jobs start at boot. systemd and launchd restart failed processes; the Windows task retries up to 999 times. The agent also reconnects to the tracker with exponential backoff while its process is alive, so temporary network loss normally does not require a process restart. A macOS or Windows operator must remain logged in for continuous operation.

Every day the agent checks the tracker's signed stable-release manifest. It accepts only an unexpired Ed25519-signed manifest and a matching SHA-512 tarball. Before installation it makes a temporary local backup of the currently installed package. The new CLI must pass a local health check; otherwise the updater attempts to restore that backup without relying on a registry download. The signed updater suppresses automatic bootstrap while it replaces its own global package, so it cannot regenerate credentials or restart itself midway. The temporary copy is not a durable recovery artifact. The post-install health check validates Node.js, native WebRTC construction, configuration, and the pinned release key; live tracker reachability is checked by doctor, not by the rollback gate. A missing key or manifest is a safe no-op. A pinned key is never silently replaced.

Privacy and security

• Target names resolve exclusively through direct DNS-over-HTTPS requests to https://1.1.1.1/dns-query, with https://1.0.0.1/dns-query as fallback. The OS resolver is never used for proxied targets.
• Every resolved address is checked before use and pinned to the outgoing connection. Loopback, private, link-local, multicast, documentation, and other special-purpose ranges are rejected to prevent SSRF and DNS rebinding.
• The process does not log client addresses, destinations, URLs, headers, request bodies, or response bodies. It retains only aggregate operational counters and generic error categories in memory.
• There is no operator-configurable or tracker-enforced concurrent-user limit. Active sessions are reported only so browsers can prefer less-busy nodes. Fixed per-request, per-session memory, message, and timeout safety bounds remain enforced and cannot be raised by an operator.
• ICE discovery is restricted to unauthenticated STUN/STUNS. Operator-provided TURN relays are rejected, and Roxxie carries no proxy payload through the tracker.
• Raw TCP proxying and the old outer WSS data fallback are absent. Normal website HTTP, HTTPS, WebSocket, and secure WebSocket traffic remains supported over the browser-to-node WebRTC channel.

This is a single-hop public proxy, not Tor. The selected exit node sees the user's public IP, destinations, URLs, headers, and proxied content. That includes HTTPS and WSS semantics/content: the node is the client-side endpoint of the upstream TLS connection even though TLS still protects that connection from third-party observers. WebRTC DTLS protects the browser-to-node hop. “No logging” is enforced by the distributed software but cannot prevent a malicious operator from modifying their copy.

Build and test

pnpm --filter roxxie-transports-tracker-protocol build
pnpm --filter roxxie-transports-adrift-protocol build
pnpm --filter roxxie-transports-node test
pnpm --filter roxxie-transports-node verify:pack

The published archive includes the preferred TypeScript source, tests, tsconfig.json, license, README, and compiled runtime. Every pack rebuilds the runtime and verifies the actual npm file list, version constants, executable CLI mode, dependency specifications, and absence of secret-like artifacts.

The package is licensed under AGPL-3.0-only.