# urnet-tools (Go) β€” Provider-Aware Fleet Ops > Applies to v3.23.0-fix.27.0+ (updated through v3.23.0-fix.32.9). The legacy shell tool (POSIX `Provider_Install_Linux.sh` + Windows `urnet-tools.ps1`) is replaced by a single provider-aware Go binary. Subcommand names and usage are preserved and expanded; what changed is **how the tool decides which provider it operates on**. ## Why this exists The legacy `urnet-tools` resolved its target from a hardcoded path (`$HOME/.local/share/urnetwork-provider`) with zero awareness that other providers exist on the box. On a multi-provider machine it could act on the **wrong provider entirely** β€” and did (08-08 pool-wipe, 08-09 half-update). The Go rewrite makes the tool's single most important guarantee structural: **it never guesses which provider you mean.** ## The two binaries | Binary | What it manages | |---|---| | `urnet-tools` | Process/systemd providers (`--proxy_file`, internal config, systemd units) | | `urnet-docker` | Docker-deployed providers (discovers containers, delegates via `docker exec`) | Both are cross-compiled from one Go source β€” the shell↔PowerShell drift is gone. --- ## πŸ“‹ Complete Command Reference ### Core & Lifecycle Commands | Command | What it does | |---|---| | `providers` (`list`, `ps`) | List providers: your own OS user's by default, or all providers on the box with `--all` (JWT identities, systemd units, state dirs). | | `status [target]` | Show detailed status. On Linux, displays live `systemctl status` view; on Windows/macOS, renders styled panel. The live block's pressure row prints the provider's one-sentence pressure summary (the `summary` from `~/.urnetwork/pressure_status`) when the provider writes it; older providers show the bare score. | | `start [target]` | Start provider service/process. | | `stop [target]` | Stop provider service/process. | | `restart [target]` | Restart provider service/process. | | `hot-restart [target]` | Restart provider unit behind confirm gate (`-f` skips prompt). | | `reinstall [target]` | Cleanly reinstall provider binary (delegates to latest updater). | | `uninstall [target]` | Uninstall provider, unit files, and optional state. Confirm-gated. | | `update [target]` | Update provider to the latest release (or `--tag `). Digest-verified. | | `hotswap` (`hot-swap`) | Zero-downtime in-process binary reload: hands live service to a verified candidate with no restart. Requires a `Type=notify` unit; see the deep-dive below. | | `self-update` (`selfupdate`) | Update the tool binary itself without touching running providers. | | `logs [target] [N]` | Stream provider logs (N lines, default 250). RAMLOGS-aware. The ramlog and file views use a native follower, so they work on Windows (no `tail` needed) and wherever `tail` is missing. It prints the last N lines and then follows. If the log is rotated or replaced it finishes the old file and follows the new one from its start, and a truncated log is followed from its start. | | `version` (`--version`, `-v`) | Print stamped binary version and build metadata. | ### Restored Provider & Session Commands (v3.23.0-fix.30.4+) | Command | What it does | |---|---| | `auth [target] [-f]` | Authenticate provider with an auth code. `-f` forces overwrite of existing JWT. Drops privileges to run as target user when called by root. | | `direct [on\|off\|status] [target]` | Toggle or report direct/local IP providing state. Taking effect immediately via reload. Available across `provider`, `urnet-tools`, and `urnet-docker`. | | `show-ip [on\|off\|status] [target]` | Control whether the provider appends its public IP to the dashboard label set by `rename`. Renamed from `ip-detect` in v3.23.0-fix.31.0, which is kept as an alias. This is about what the dashboard shows, not which address the provider serves on; for that see `direct`. | | `sn-status [--json] [target]` | Query and display Subnet 25 mining & node telemetry (v3.23.0-fix.30.9+): global rank, top-200 tier eligibility, net bandwidth provided, registered coldkey (SS58/Hex), current subnet epoch blocks, and finalized epoch pool payout share. Available across `urnet-tools`, `urnet-docker`, and `provider`. | | `usage [graphs\|graph ] [target]` | Display traffic & billing accounting: billable relay bytes vs control-plane protocol overhead, with rolling time-series summaries. Available across `urnet-tools` and `urnet-docker`. | | `choose-network [target]` | Point provider to custom API and WebSocket signaling endpoints. Use `--reset` to restore default bringyour endpoints. | | `fast-auth [on\|off\|status] [target]` | Toggle or check `~/.urnetwork/fast_auth` marker to bypass auth rate limiter. Confirm-gated. | | `set [help \| \| off \| ] [target]` | Get, set, or clear a runtime provider override over the control socket. `urnet-tools set help` lists every key with its value domain and what it changes. The keys are `node-name`, `report-url`, `report-interval`, `fast-auth`, `self-heal`, `proxy-url-max`, `proxy-url-refresh`, `cleanup-scope`, `cleanup-interval`, `hot-restart`, `oom-cap`, `smart-dialer`, `gomemlimit`, `gogc`, `profile`, `ramlogs`, `metrics`, `metrics-listen`, `h3`, `h3-datagram`, `h3-datagram-send`, `baseline` and `proxy-audit`. Most apply live on the next tick; `profile` and `ramlogs` need a restart. Queued to `pending_overrides.json` if the provider is stopped. Confirm-gated. | | `rename [target]` | Set the dashboard identity label on the backend. Alias for `set node-name `. Writes `~/.urnetwork/node_name`, re-read on next tick β€” no restart. Use `off` to clear. Available across `urnet-tools` and `urnet-docker`. | | `session save [target]` | Export encrypted AES-256-CBC bundle of provider JWT identity and state. Prompts for passphrase. | | `session load [target] [--allow-different-account]` | Decrypt and load identity bundle into provider. Automatically backs up current state first. Verifies account identity unless bypassed. | | `self-heal [on\|off\|status] [target]` | Toggle or query resource-pressure self-healing monitor (`~/.urnetwork/proxy_self_heal`). | | `default [set \| show \| clear]` | Persist, inspect, or clear default provider target for current user in `os.UserConfigDir()/urnet-tools/default`. | #### OpenRC (Alpine) command parity On a host where OpenRC is the running init system and the installer's `urnetwork` service exists, the lifecycle commands act on that service. The backend is chosen at run time by looking at the running init system, never by operating system. A host where systemd is running keeps the systemd behavior even if OpenRC is installed beside it. The install walkthrough is in [Installation: Alpine Linux (OpenRC)](Installation.md#-alpine-linux-openrc). | Command | What it runs on OpenRC | |---|---| | `start` | `rc-service urnetwork start` | | `stop` | `rc-service urnetwork stop` | | `restart` | `rc-service urnetwork restart`, behind the usual confirm gate (`-f` skips the prompt) | | `auto-start on` / `off` | `rc-update add urnetwork default` / `rc-update del urnetwork default` | | `auto-update daily\|weekly\|monthly` / `off` | A busybox `crond` entry in `/etc/periodic//urnetwork-update` that runs `urnet-tools update -f`. There is no systemd timer. `off` removes it from every interval. | | `logs [N]` | Follows the service's log file, `/var/log/urnetwork.log` (the file named by `output_log` in `/etc/init.d/urnetwork`), falling back to the error log. | | `status` | Prints `rc-service urnetwork status`, then the usual table with the live control-socket view. | | `uninstall` | When it targets the service's provider: stops the service, runs `rc-update del`, removes `/etc/init.d/urnetwork` and clears the auto-update entry. | `auto-update` only fires while `crond` is running. If it is not, the command still writes the entry and prints a note with the commands to enable `crond`. These commands need root, because they change a system service. Run as an ordinary user, a failing command adds a hint to re-run as root. `update` also restarts the service, with a stop/start instead of a HotSwap. See [HotSwap](HotSwap.md#not-available-under-openrc-alpine). **Ambiguity is refused on purpose.** `start` is not gated. But a `stop` or `restart` with no selector, on a box where the service runs beside another provider, is refused rather than acted on. Stopping only the service would leave the other provider running while the tool reported success. Name the target with `--user`, `--unit` or `--state-dir` (the selectors in [Targeting & Selectors](#-targeting--selectors)): ```text N providers found on this box, specify a target: [alice (pid 4242)] urnet-tools stop --user # a specific provider urnet-tools stop --unit urnetwork # the OpenRC service urnet-tools providers # list what was found ``` `N` is the provider count the tool reports, and the bracketed list names the providers that are not the service's own (here, `alice`'s). `restart` prints the same message with `restart` in the example commands. A selector that matches the service's own provider, such as `--unit urnetwork` or `--user urnet`, goes straight to `rc-service`. ### Proxy Management Commands | Command | What it does | |---|---| | `proxy add [target]` | Merge proxies from text file (`host:port[:user:pass]`) or live URL. Supports straight paths with `~`, URLs (auto-routed to `add-source`), and flags (`--file=`, `--proxy_file=`, `--url=`). | | `proxy paste [target]` | Stream raw proxies from stdin or pipe without creating host files. Auto-detects formats and URLs. | | `proxy clear [target]` | Remove all proxies and URL sources. Confirm-gated (`-f` bypasses prompt). | | `proxy remove [addresses...] [target]` | Remove specific proxies or patterns. Use `--match=` for host substring matches, or `--all` for complete wipe. | | `proxy trim [target] [--preview]` | **(New in 30.4)** Set persistent hard cap of `` running proxies. Sheds worst A-F reachability graded proxies first. `proxy trim off` clears the cap. | | `proxy refresh [target] [--force]` | Reload proxy list into running provider without restarting. `--force` bypasses warmup lockout. | | `proxy add-source [target]` | Add live URL proxy source. Fetched and probed immediately. | | `proxy remove-source [target]` | Remove URL proxy source. | | `proxy ids [target]` | **(New in 31.0)** Show the `client_id` the platform assigned to each proxy, including the `direct` transport. Read from the provider's local client-JWT store; the bearer tokens themselves are never printed. | | Exclusion via `proxy remove --match=` | See `proxy remove` above. `--match=` removes matching proxies and persists the pattern so future URL refreshes skip them. There is no `proxy exclude` subcommand. | | `proxy health [target]` | Display live health state (Up, Down, Dead, Degraded). | | `proxy traffic [target]` | Display bandwidth, billable traffic, and active NAT sessions per proxy. | | `proxy remove-dead [target]` | Interactively prune dead and degraded proxies. Honors `--dry-run`. | | `summary [target]` | Fleet-style summary of proxy counts by source (url, file, internal). Top-level command, not a `proxy` subcommand. | ### Hub Command Family (v3.23.0-fix.30.4+) > [!WARNING] > **Deprecated (v31.3+):** The hub commands have been removed from `urnet-tools`. This section is retained for historical reference only. | Command | What it does | |---|---| | `hub init` | Initialize and configure the bandwidth hub service on this machine. Prompts for password (min 8 chars) or reads from stdin. | | `hub link ` | Pair provider with a remote bandwidth hub. Verifies TLS CA or SHA-256 certificate fingerprint (TOFU security). Confirm-gated on identity change. | | `hub unlink` | Unlink provider from bandwidth hub. | | `hub test` | Test reachability and TLS certificate chain validation to the configured hub. | | `hub onboard-cmd` | Generate one-line onboarding command with URL-escaped tokens for remote providers. | | `hub show-password` | Display current hub admin access password. | | `hub open-port` | Configure firewall rules (ufw/iptables/firewalld) to open hub listener port. Confirm-gated. | | `hub update` | Update bandwidth hub binary to latest release. | | `hub set ` | Set raw reporting endpoint URL in `~/.urnetwork/report_url`. | | `hub off` | Disable hub reporting by clearing `report_url`. | | `hub install` | Install bandwidth hub binary and systemd service. | ### System & Performance Tuning | Command | What it does | |---|---| | `auto [on\|off]` | Enable or disable Smart Auto hardware profile. | | `optimize [-f]` | Tune kernel parameters (conntrack, socket buffers, port ranges, BBR). Platform-aware. Self-elevates to root when needed (apply live + persist atomically, or roll back). | | `eco [on\|off]` | Enable or disable Eco profile (RAM-constrained hosts). | | `smart-dialer [status\|on\|off]` | **(New in 32.8)** Show or set the measured-cost transport preference. Live, persisted, off by default. `status` says which way it is set and how to change it. See [Configuration](Configuration.md#-control-socket--runtime-settings). | | `set oom-cap [on\|off\|shadow]` | **(New in 32.8)** Show or set the OOM-aware start cap kill switch. `shadow` (default) decides and logs and enforces nothing, `on` enforces, `off` disables it and forgets a standing cap. Any source saying `off` wins. Live and persisted. | | `set h3 [on\|off]` | **(New in 32.9)** Show or set the H3 (QUIC) transport on the **direct** identity, live and persisted. Off by default, except on a node with no proxy source configured, where it turns on automatically once startup settles. An explicit `set h3 off` always wins. On lets the idle transport dial; off closes a live connection and stops further dials, and neither counts as a drop. Clearing it hands the decision back to `URNETWORK_H3`. See [Configuration](Configuration.md#-control-socket--runtime-settings). | | `set h3-datagram [on\|off]` | **(New in 32.9)** Offer QUIC DATAGRAM (RFC 9221) on the H3 connection, so a server that accepts can send its small frames as datagrams instead of on the reliable stream. Off by default (on automatically for a node with no proxy source, like `h3`), receive side only, no environment variable. | | `set h3-datagram-send [on\|off]` | **(New in 32.9)** Also send small frames as datagrams on a connection where the server accepted them. Off by default (on automatically for a node with no proxy source, like `h3`), read per message, and used only while H1 is up. | | `autopilot log [limit]` | **(New in 32.8)** Show the capacity decisions the provider recorded (OOM-aware start cap and trim results) as a timeline: UTC time, actor, action, the change, the mode and the reason. Shadow decisions show as `[shadow]`. Also prints the current `oom-cap` value. Default 20 entries, at most 200. A provider that predates the `ledger` command answers with an explanatory error. | `baseline show [-n N] [--json]` | **(New in 32.8)** Show the newest rows of this box's own behaviour record: UTC time, kind, version, proxies up against desired, RSS, host memory available, swap, and the file's first and last timestamps and size. Default 20 rows, at most 200. Reads `~/.urnetwork/baseline.jsonl` directly, so it works on a box whose provider is stopped. | | `baseline mark