Device guide · Docker · Node.js client 1.6.6

Run a bandwidth-sharing peer in Docker

There is no prebuilt PROXIES.SX image. The documented way to run the peer in Docker is the official Node.js reference client inside the public node:20-alpine image, with your SDK / device key in an environment variable and a named volume that keeps the device identity across restarts. It suits a home server, NAS or Unraid box on a residential connection.

Registration does not guarantee traffic or earnings. Earnings depend on eligible traffic your devices actually serve and on your active partner terms.

Checked on against our published supplier terms

What runs in the container

Base image
node:20-alpine, as in the official guide. Node 20 is end-of-life and no longer among Docker Hub's supported tags
Client
reference-sdk.js 1.6.6, 54,448 bytes, from agents.proxies.sx
SHA-256 on 12 Oct 2026
0a08004bb0f83fecf3d54ea8c7c5fe2146bbf7e28ab54fa742c021e51e6e4e66
Dependency
ws (WebSocket library), installed by npm on first start
Environment
API_KEY (required), PEER_STATE_FILE, optional WALLET, RELAY_URL, CONNECTION_METHOD
Relay sockets
WS_CONNECTIONS, default 1, clamped to 5 (the relay accepts at most 6 per device)
Network
Outbound only; no published ports

Run it

  1. Get a key and declare your supply

    Create a farmer account, sign Partner Agreement 2.0, complete the supply-source declaration and create an SDK / device key. We approve each signed agreement before the relay admits devices; until then the log shows close code 1013 and the client keeps retrying by itself. Use only a connection whose owner has given informed consent.

  2. Start the container

    This is the one-liner from the official peer guide with -w /app added: without a working directory, npm i ws fails in / on current node:20-alpine images and the container restarts in a loop. The volume persists the identity, so a restart reuses the same device; AGENT_NAME is left unset on purpose so each container uses its own hostname.
    Shell
    docker run -d --name proxies-peer \
  -e API_KEY=psx_your_key \
  -e PEER_STATE_FILE=/state/id.json \
  -v proxies-peer-state:/state \
  --restart unless-stopped \
  -w /app \
  node:20-alpine sh -c "[ -e node_modules/ws ] || npm i ws; [ -f reference-sdk.js ] || wget -qO reference-sdk.js https://agents.proxies.sx/peer/reference-sdk.js; node reference-sdk.js"

  3. Watch it register

    Look for REGISTERED, CONNECTED and ACK. A device goes on sale only after we have approved your signed agreement and the device has passed the automatic test through its tunnel, including the throughput floor returned as throughputContract.minKBps at registration (126 KiB/s on 12 October 2026).
    Shell
    docker logs -f proxies-peer

Pin the client you reviewed

The one-liner downloads reference-sdk.js on first start. If you prefer to read the file first and keep running that exact copy, download it yourself and mount it read-only.
Shell
mkdir proxies-peer && cd proxies-peer
curl -fLO https://agents.proxies.sx/peer/reference-sdk.js
shasum -a 256 reference-sdk.js      # compare with the published client you reviewed

docker run -d --name proxies-peer \
  -e API_KEY=psx_your_key \
  -e PEER_STATE_FILE=/state/id.json \
  -v proxies-peer-state:/state \
  -v "$PWD/reference-sdk.js:/app/reference-sdk.js:ro" \
  -w /app --restart unless-stopped \
  node:20-alpine sh -c "[ -e node_modules/ws ] || npm i ws; node reference-sdk.js"
docker-compose.yml (same setup)
services:
  proxies-peer:
    image: node:20-alpine
    container_name: proxies-peer
    restart: unless-stopped
    working_dir: /app
    environment:
      API_KEY: psx_your_key
      PEER_STATE_FILE: /state/id.json
    volumes:
      - proxies-peer-state:/state
      - ./reference-sdk.js:/app/reference-sdk.js:ro
    command: sh -c "[ -e node_modules/ws ] || npm i ws; node reference-sdk.js"
volumes:
  proxies-peer-state:

What we checked on 27 September 2026

We ran the built-in offline self-test of client 1.6.0 in node:20-alpine on linux/amd64; it was not repeated for the current client. It exercises reconnects, token refresh, relay redirects and failover against a simulated relay; it registers only a simulated device and contacts no real server.
Output (trimmed)
$ docker run --rm -v "$PWD":/app -w /app node:20-alpine sh -c \
    'node --version; npm i ws@8; SELFTEST=1 node reference-sdk.js'
v20.20.2
added 1 package in 2s
[CONNECTED] slot=0 deviceId=dev1 relay=wss://relay.proxies.sx
[CLOSED] slot=0 code=4008 reason=pool cap exceeded
[SLOT 0] relay throttled us (4008); backing off 0s
[TOKEN] refreshed; next refresh in 60m
[REDIRECT] switching relay wss://relay.proxies.sx -> wss://relay-us.proxies.sx (geo)
[RELAY_FAILOVER] wss://relay-us.proxies.sx unreachable x2 -> failing over to wss://relay.proxies.sx
[SELFTEST] PASS

$ node reference-sdk.js        # without API_KEY
API_KEY env required

Home servers, NAS and Unraid

Where the container fits
HostNotes
Unraid, TrueNAS SCALE, Synology Container ManagerUse the compose file above, or the same image, environment and volume in the web UI. Keep the state volume on persistent storage.
ProxmoxRun Docker inside a VM or LXC container that has outbound internet access.
A VPS or cloud VMRuns, but a datacenter IP is never listed as residential or mobile.
Many containers on one connectionThey share one exit IP; duplicates are not extra exits. Run one per real connection.

Stop and remove

Shell
docker rm -f proxies-peer
docker volume rm proxies-peer-state   # deletes the device identity

Remove the device in the farmer dashboard as well. You can leave at any time; earnings already recorded stay on your account.

Questions

Is there an official Docker image for the PROXIES.SX peer?
No prebuilt image is published. The documented method runs the official Node.js reference client inside the public node:20-alpine image, downloading reference-sdk.js and its one dependency, ws, on first start.
Can I run several containers on one machine?
Each container gets its own identity from its hostname, but containers behind the same connection share one exit IP, and duplicates on one IP are not extra distinct exits. Run one container per real connection.
Will it earn on a VPS or cloud server?
The container runs anywhere Docker does, but a datacenter IP is never listed as residential or mobile. It needs a residential or mobile connection, such as a home server, NAS or mini PC.
Does it work on a Raspberry Pi or Apple Silicon?
node:20-alpine is published for arm64 as well as amd64, and the reference client is plain JavaScript. We ran our test on linux/amd64 only, so we have not verified arm64.
Why does the volume matter?
The state file keeps the device identity. With the volume, a restart reuses the same device and refreshes its token; without it, every re-created container (for example after an image update) registers a new device, which also makes registration rate limits (HTTP 429) more likely.
Should I set AGENT_NAME?
Not in the one-liner. The client defaults to the container hostname, so each container is its own device. Giving many containers the same name collapses them into one device.

Run one container on a home connection

Create a farmer account and an SDK / device key, start one container, and expand only after it passes the self-test, is verified and listed, and has carried customer traffic.
Create farmer account Read the supplier contract

Sources