Skip to content

Commit 1daf070

Browse files
echobtechobt
authored
Merge pull request #38 from BaseIntelligence/mission/compute-plane
docs(validator): compute-requirements table + turnkey install with auto-update
2 parents 2dfec73 + 2f7361f commit 1daf070

1 file changed

Lines changed: 114 additions & 9 deletions

File tree

‎docs/validator/README.md‎

Lines changed: 114 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,119 @@
1-
# Validator Submitter Guide (Docker Swarm)
1+
# Validator Guide (Docker Swarm)
22

3-
This guide is only for normal validators. It installs the submit-only on-chain
4-
weight submitter as a systemd service. The submitter fetches the master weight
5-
vector from the public BASE endpoint and submits it on-chain. It runs
6-
no challenge orchestration: all challenge services run on the BASE
7-
master (manager) node.
3+
This guide covers running a BASE validator on Docker Swarm. There is no
4+
Kubernetes anywhere in BASE: the only backend is Docker Swarm.
5+
6+
A validator runs in one of a few profiles, from a submit-only on-chain weight
7+
submitter through a full challenge-evaluating validator node. The
8+
[Compute Requirements](#compute-requirements) below size each profile, and the
9+
[Automatic Install (One Command)](#automatic-install-one-command) section brings
10+
up a self-updating validator node with the turnkey installer.
11+
12+
The simplest profile is the submit-only on-chain weight submitter, installed as a
13+
systemd service. The submitter fetches the master weight vector from the public
14+
BASE endpoint and submits it on-chain. It runs no challenge orchestration: all
15+
challenge services run on the BASE master (manager) node.
816

917
The default weights endpoint is:
1018

1119
```text
1220
https://chain.joinbase.ai/v1/weights/latest
1321
```
1422

23+
## Compute Requirements
24+
25+
How much compute a validator needs depends on which evaluation work it performs.
26+
The numbers in this table are authoritative.
27+
28+
| Validator profile | Compute |
29+
|-------------------|---------|
30+
| Submit-only / simple validator (no challenge execution) | 2 vCPU, 4 GB RAM |
31+
| Validator running the base (agent-challenge) evaluation | 8 vCPU, 32 GB RAM |
32+
| PRISM challenge | No additional compute required |
33+
34+
PRISM adds no compute to the validator: its heavy GPU evaluation is **delegated
35+
to miner-funded worker agents** (the worker plane), and the validator only
36+
performs light verification plus probabilistic replay audits. A validator
37+
therefore never needs a local GPU for PRISM.
38+
39+
## Automatic Install (One Command)
40+
41+
`deploy/swarm/install-swarm.sh` is the automatic, one-command install path. On a
42+
blank host it installs everything it needs: Docker Engine (its `ensure_docker`
43+
step), the `uv` runtime (its `ensure_uv` step, when the supervisor is installed),
44+
and the Docker Swarm (`swarm init`).
45+
46+
### Dry-run by default
47+
48+
The installer is **dry-run by default**: with no flags it prints every planned
49+
command via its `plan` gate and changes nothing. Pass `--apply` to execute.
50+
Every destructive step stays behind its own explicit flag, so nothing mutates
51+
until you opt in.
52+
53+
```bash
54+
bash deploy/swarm/install-swarm.sh --help # list flags + required env
55+
bash deploy/swarm/install-swarm.sh # dry-run: prints the plan, changes nothing
56+
```
57+
58+
### Auto-update (base-supervisor image-updater)
59+
60+
`--validator-node` brings up `base validator agent` as an **auto-updatable**
61+
Docker Swarm service (`base-validator-agent`) plus a node-local base-supervisor
62+
whose image-updater digest-pins that service on every new
63+
`base-validator-runtime:latest` digest. That image-updater **is** the
64+
auto-update: the validator's `base` code rolls forward automatically, with no
65+
manual `docker service update`.
66+
67+
`--install-supervisor` enables the `base-supervisor.service` systemd unit, the
68+
control-plane auto-update unit. Its image-updater runs on a 60s interval, and
69+
optional base self-update is wired only when `SUPERVISOR_SELF_UPDATE_MANIFEST_URL`
70+
is set (otherwise self-update is explicitly disabled, never left inert).
71+
72+
### Quick start: validator node (dry-run first, then `--apply`)
73+
74+
Set the required environment, run a dry-run to review the plan, then re-run with
75+
`--apply` (adding `--install-supervisor` to enable the node-local auto-update
76+
unit).
77+
78+
Required environment for `--validator-node`:
79+
80+
- `VALIDATOR_MASTER_URL`: the MASTER coordination/gateway root (for example
81+
`http://<master-host>:19080`). There is no default: a validator must never
82+
point at its own advertise address, so an unset value fails fast.
83+
- `VALIDATOR_BROKER_TOKEN`: the validator's own broker token (mounted at
84+
`/run/secrets/base_broker_token`).
85+
- the validator hotkey wallet, staged under `VALIDATOR_WALLET_PATH` (default
86+
`/var/lib/base/wallets`), wallet name `VALIDATOR_WALLET_NAME`.
87+
88+
`VALIDATOR_CAPABILITIES` selects the evaluation work this node performs:
89+
90+
- `["cpu"]` (default): the base agent-challenge (Terminal-Bench) CPU
91+
evaluation.
92+
- PRISM GPU evaluation is **delegated** to the miner-funded worker plane, so a
93+
validator needs no GPU capability for PRISM; it only performs light
94+
verification plus probabilistic replay audits. (`["gpu","cpu"]` remains
95+
available for the legacy path where a validator itself runs PRISM GPU
96+
re-execution at concurrency 1.)
97+
98+
```bash
99+
export VALIDATOR_MASTER_URL="http://<master-host>:19080"
100+
export VALIDATOR_BROKER_TOKEN="<validator-broker-token>"
101+
export VALIDATOR_CAPABILITIES='["cpu"]' # base agent-challenge; PRISM is delegated
102+
# stage the validator hotkey wallet under /var/lib/base/wallets first
103+
104+
# 1) DRY-RUN (default): prints the planned docker swarm commands, changes nothing
105+
bash deploy/swarm/install-swarm.sh --validator-node
106+
107+
# 2) APPLY: execute, and enable the node-local auto-update supervisor unit
108+
bash deploy/swarm/install-swarm.sh --validator-node --apply --install-supervisor
109+
```
110+
111+
The dry-run renders the node-local supervisor config
112+
(`validator_agent_target_enabled: true`, watching
113+
`base-validator-runtime:latest`) and the per-validator `validator.yaml`, and
114+
prints the `docker service create base-validator-agent ...` it would run. Review
115+
that plan before you pass `--apply`.
116+
15117
## Secret Rule
16118

17119
The submitter needs exactly one secret: the validator hotkey. Never place coldkey
@@ -93,9 +195,12 @@ dependency.
93195

94196
### What are the minimum requirements?
95197

96-
A submit-only node needs very little: a Python runtime, network access to the
97-
master endpoint and the chain, and the validator hotkey file. A node that also
98-
acts as the Swarm manager should have at least 2 vCPUs and 8 GB RAM.
198+
See [Compute Requirements](#compute-requirements) above for the authoritative
199+
sizing per validator profile. In short: a submit-only node needs very little (a
200+
Python runtime, network access to the master endpoint and the chain, and the
201+
validator hotkey file) and fits in 2 vCPU / 4 GB RAM. A validator that runs the
202+
base agent-challenge evaluation needs 8 vCPU and 32 GB RAM; PRISM adds no compute
203+
because its GPU evaluation is delegated to the miner-funded worker plane.
99204

100205
### What if the requirements are too high?
101206

0 commit comments

Comments
 (0)