# Linux x86-64 headless peer 1.6.1

This package is a standalone command-line program: no GUI, Go, Docker, Node.js
or compiler is needed on the device. It needs Linux x86-64, outbound DNS/HTTPS/
WebSocket and target TCP access, an OS CA certificate store, and a valid farmer
SDK/device key. The optional service installer requires systemd 235+ and sudo.
Only deploy on devices with informed end-user consent and a current agreement.

## Required source declaration

Complete https://farmer.proxies.sx/settings#peer-source with the device owners and
upstream suppliers, app/distribution channels, countries and network types, informed
permission before traffic, and withdrawal process. Use your preferred language and
keep the declaration current. Submission is not independent KYC or proof of consent;
secure identity/business verification is being prepared. Do not email or paste identity
documents, secrets, end-user lists or exit IPs. Source collection does not introduce
a new automatic registration gate or change an existing signed agreement.

## Install one device first

Download from https://agents.proxies.sx/peer/releases/1.6.1/:

    curl -fLO https://agents.proxies.sx/peer/releases/1.6.1/proxies-peer-linux-amd64.tar.gz
    curl -fLO https://agents.proxies.sx/peer/releases/1.6.1/SHA256SUMS
    sha256sum -c SHA256SUMS
    tar -xzf proxies-peer-linux-amd64.tar.gz
    cd proxies-peer-linux-amd64
    sudo bash install.sh

The installer asks privately for the SDK key and creates a stable random device
name once. It keeps the key in /etc/proxies-peer/peer.env (root-only, 0600), runs
as a systemd dynamic unprivileged user, and persists identity in
/var/lib/proxies-peer/state.json. Keep BOTH configuration and state across
restarts. Never copy a populated state/config directory into a device image.
Existing configuration is retained; an already-running service is not replaced.
For fleet automation provision a distinct stable AGENT_NAME per real device and
a private 0600 EnvironmentFile before invoking install.sh. Never clone one name
or state across devices. Stage the rollout centrally; jitter alone is not pacing.

    /usr/local/bin/proxies-peer -version
    sudo systemctl status proxies-peer --no-pager
    sudo journalctl -u proxies-peer -n 40 --no-pager

Expect REGISTERED (or RESUMED), CONNECTED and ACK. Regional relay hostnames vary.
The installer starts with one socket per device; SDK default outside this
installer is four, normally clamped to five, hard maximum six. Do not increase
sockets across a whole fleet without observing relay resources and NAT limits.

## Without systemd

Extract the same package. Run as an ordinary dedicated user with a persistent,
private HOME/state path. Read the key privately instead of putting it in shell
history or command-line arguments:

    read -r -s -p 'SDK key: ' API_KEY; echo
    export API_KEY
    export AGENT_NAME='your-stable-unique-device-name'
    export PEER_STATE_FILE="$HOME/.local/state/proxies-peer/state.json"
    export WS_CONNECTIONS=1 REGISTER_JITTER_MS=30000
    ./proxies-peer

These are Bash commands. To stop, press Ctrl+C. Your orchestrator must preserve
state, use bounded restarts, and stop retrying persistent 401/403 responses while
support checks key/account/agreement status. Outbound access is required; no
inbound port or root network capability is required by the SDK itself.

## Registration returns HTTP 403

Compiling `reference-sdk.go` yourself is supported. The source build and the
published binary use the same registration endpoint and account checks; switching
between them does not remove a server-side account restriction.

A valid SDK key can still receive 403 when its owner account is suspended, the
current Partner Agreement is missing, or a hard device limit is reached. A login
that works does not by itself prove device registration is enabled. The current
Go client reports the HTTP status without the server's detailed rejection body,
so the number alone does not identify which check failed.

1. Sign in to the same account at https://farmer.proxies.sx and check the existing
   key in **API Keys** and the current agreement in **Partner Agreement**.
2. Ask support to check the account's registration status. Supply the account
   email, key **name**, one stable device name, SDK version and UTC error time.
   Never send the key, token or state file. An account restriction needs review
   on our side; generating more keys or repeatedly rebuilding is not a remedy.
3. After support confirms the restriction is cleared, retry **one** device with
   its original key/name/state. Look for `REGISTERED` or `RESUMED`, then
   `CONNECTED` and `ACK`, before increasing the cohort.

Do not delete identity state, randomize names or start the whole fleet to diagnose
403. HTTP 401 and 429 are different outcomes; for 429 retain the retry/backoff
behavior described below.

## Changes and limits

1.6.1 adds REGISTER_JITTER_MS (default 30000, maximum 3600000), up to five total
registration attempts on transient failures/429/5xx with exponential backoff,
jitter and Retry-After (seconds or HTTP date), atomic 0600 identity writes that
fail visibly, 128-bit generated names, and key/name binding for saved state.
Relay wire protocol is unchanged. Keep the original key/name/state when updating.
Named legacy state migrates once by registering the same key and name; old state
without a saved name needs the original explicit name. Corrupt state requires
review/restoration; do not delete it blindly or randomize identities on errors.

Server identity is agent_ plus the first 16 hexadecimal characters of
SHA256(apiKey + ':' + name). Changing a key or name can create a new identity.
No fleet/throughput capacity is guaranteed by successful installation.

Start with one device, then a small controlled cohort, then progress toward the
agreed 5,000-device pilot only after checks. At each stage verify online,
verified, listed, real customer routing, country/IP classification, stable
restart identity, successful token refresh, usage metering and resource headroom.
Arrange an onboarding window with support; do not start thousands together.
Online + verified alone does not prove listed/routable or paid customer demand.

Current production account caps were 200,000 total / 20,000 unproven devices at
2026-09-25 audit; limits can change. The observed routing throughput floor was
500 KB/s, with other quality, consent, geo and account checks. Verification and
quality probes are separate queue-based processes; neither five probes nor a
fixed completion time is guaranteed. Multiple devices behind carrier NAT may
share an IP: duplicates are not extra distinct exits. The SDK does not bind
separate processes to separate modems; uplink isolation requires your network
configuration. Do not lower mobile/consent/quality requirements to grow counts.

A production routing self-test needs separate customer proxy credentials and an
existing traffic balance or a support-arranged test. Never use the farmer API key
as a proxy password or buy a package simply to prove that this installer starts.
Report UTC time, SDK version, one device name/ID and redacted logs to support.
Never send keys, refresh tokens, state files or full environment files.

## Stop / uninstall

    sudo systemctl disable --now proxies-peer

Stopping disconnects this device's tunnels. Keep state for a later restart.
For permanent removal, stop the process first, remove the device from the farmer
dashboard, then delete its local secrets/state according to your retention rules.
Do not revoke a shared fleet key merely to remove one device.