Skip to content

docs(book): add node operator guide - #652

Open
Sahilvishnaliya wants to merge 1 commit into
PsycheFoundation:mainfrom
Sahilvishnaliya:docs/node-operator-guide
Open

docs(book): add node operator guide#652
Sahilvishnaliya wants to merge 1 commit into
PsycheFoundation:mainfrom
Sahilvishnaliya:docs/node-operator-guide

Conversation

@Sahilvishnaliya

Copy link
Copy Markdown

Summary

Adds a new top-level book chapter: the Node Operator Guide (explain/operator-guide.md) — a field manual for people who run Psyche training nodes over time, complementing the existing one-time setup docs (Quickstart: Compute Provider, Joining a run).

What it covers:

  • What you actually operate: the split between run-manager (supervisor), the auto-pulled client container, the Solana keypair, RPC endpoints, and the host GPU stack — and which parts are managed for you vs. manual.
  • Node lifecycle from the operator's seat: a mermaid diagram of the epoch phase machine (WaitingForMembers → Warmup → RoundTrain/RoundWitness → Cooldown), a per-phase table of what your node is doing and the typical operator-side failure in that phase, and which log events mark epoch boundaries.
  • Rewards accrue per completed epoch: points are shared equally among clients that finish the epoch; leaving mid-epoch forfeits them.
  • Running long-term: tmux/systemd session management, a startup checklist (GPU-in-Docker check, wallet funding for tx fees, disk), and what to monitor (container, phase transitions, GPU utilization, RPC health).
  • Checking run state from the CLI: the read-only run-manager list-runs, json-dump-run, and json-dump-user commands for answering "is it my node or the run?".
  • Updating: which upgrades are automatic vs. manual, and what version-mismatch loops mean.
  • Maintenance windows: why right after an epoch ends is the safe moment to stop.
  • Delegation and multi-machine setups: one keypair per machine, delegate keypairs via join-authorization-delegate, master-key reward identity for cloud-burst fleets.
  • Claiming rewards: run-manager treasurer-claim-rewards usage.
  • Troubleshooting quick reference: a symptom → likely-cause table linking back to the Client FAQ.

Notes for reviewers

  • Technical claims verified against the codebase: run state machine in shared/coordinator/src/coordinator.rs (RunState, CoordinatorConfig), epoch-end reward accounting in the Solana coordinator program (instance_state.rs: healthy finishers earn earning_rate_total_shared / num_finishers), and the run-manager CLI surface in tools/rust-tools/run-manager/src/main.rs (list-runs, json-dump-run, json-dump-user, treasurer-claim-rewards, join-authorization-*).
  • Purely additive: one new page + one SUMMARY.md line.
  • Happy to trim sections, adjust tone, or move the chapter elsewhere in the book if you'd prefer it nested under an existing section.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant