devplacepy/nodes/client/README.md

devplace-node

Native donor client for the DevPlace community node network. One static Go binary, standard library only.

What you share

When running, and only inside the limits you configured:

• Your internet connection and your IP address, used to fetch public pages from the destinations on the allowlist (today: reddit.com, redd.it and their subdomains) over ports 80 and 443, GET only.
• The fetched public page, which DevPlace receives and may cache for a short time.
• Byte counters (up and down) so your daily cap and your lifetime totals are correct.

What is never shared

• Your cookies, logins, accounts and browser. The client has no cookie jar and drops Cookie, Authorization and Proxy-Authorization from every request. It uses no browser profile and reads no files besides its own config.
• Any access to your local network: addresses that are private, loopback, link-local, CGNAT or multicast are refused after local DNS resolution, and the connection goes to the address that was checked.
• Any destination outside the baked-in allowlist. A list sent by the server can only be equal or narrower. Redirects that leave the allowlist are refused.
• Anything on ports other than 80 and 443.

The device secret (dpn_...) is stored in the config file with mode 0600 and is never logged or printed.

Use

devplace-node login --server https://devplace.net --secret dpn_...
devplace-node status
devplace-node run
devplace-node version

Create the device secret on your DevPlace profile after consenting to bandwidth sharing. login asks the server to accept the secret before storing it (--no-verify skips that). The secret can also come from DEVPLACE_NODE_SECRET. Every command takes --config PATH.

run is quiet: it logs start, disconnects, and one totals line per day. Add -v for detail. Exit code 3 means the server ended this device for good (revoked, kill switch, no consent, not adult, replaced by another instance of the same device); fix the cause and start it again. A timed suspension is not final: on a ticket 403 or a kick with reason suspended the client waits until the until instant (at least 60 seconds, at most 24 hours, plus jitter; 5 minutes when until is empty or unreadable) and then asks for a new ticket.

When the server setting pause_on_battery is on, jobs are refused with on_battery while the machine runs on battery (Linux /sys/class/power_supply, macOS pmset -g batt, Windows GetSystemPowerStatus; the result is cached for 15 seconds). An unknown power state counts as mains power. The device label the server holds is logged at connect with -v.

Config file

Stored at <user config dir>/devplace-node/config.json, with usage.json (today's byte count) beside it.

{
  "server": "https://devplace.net",
  "secret": "dpn_...",
  "bandwidth_mb_day": 500,
  "max_concurrent": 2,
  "max_tunnels": 2,
  "active_from": "",
  "active_to": "",
  "timezone": ""
}

active_from and active_to are HH:MM in timezone (empty means the system timezone); a window may wrap midnight. These limits are enforced locally and the server can only make them stricter.

Build and package

./build.sh [outdir] cross-compiles linux/amd64, linux/arm64, darwin/arm64, darwin/amd64 and windows/amd64 with CGO_ENABLED=0 -trimpath, and writes manifest.json (name, os, arch, sha256, size, version) beside the binaries. VERSION=1.2.3 ./build.sh overrides the version.

packaging/ holds a systemd user unit (loginctl enable-linger $USER keeps it running without a login), a launchd plist, a Windows scheduled-task script and a container compose file.

Tests

go vet ./... && go test ./...