−
100%
+
fit
scroll
# Sovereign Node Recipe — Day 00357
(rebirth) How to make a Portal node its own
sovereign brain (own code + own DB), proven on
**hexperiment** Day 357. Before this,
hexperiment ran its own binary but drank from
**hexlet's** database over tailscale —
compute-only, not truly its own node. ## What
"sovereign" means A node that boots and
connects to its **own** local Postgres, not a
remote one. It mirrors the canonical node
(hexlet) but can be worked on in isolation,
then promote changes back when ready.
Production (hexlet) stays untouched until
promotion. ## The 4-move recipe 1. **Copy the
structural data.** `\copy` the `things` table
from the source node into the target's local
Postgres (data-only client COPY —
version-robust across PG 17→15). Skip
`sacred_embeddings` (RAG, ~3.3 GB,
rebuildable); structural Things are tiny (~233
MB / 120k rows). Optionally copy `beings` for
auth parity. 2. **Set the primary db-target.**
In the local DB, set the `localhost-things`
db-target Thing `ruby.primary=true`, others
false. 3. **Declare sovereignty.** Set
**`HEXCRAFT_NODE_ID`** in the node's pm2 env.
This — NOT `HEXCRAFT_DB_HOST` — is the
real switch. `db/mod.rs::init_pools` checks
`HEXCRAFT_NODE_ID.is_ok()`; a sovereign node
tries `localhost` FIRST. `HEXCRAFT_DB_HOST` is
a red herring: the host-selection logic
overrides it. 4. **Cut the umbilical.**
Delete/entomb the remote db-targets
(`hexlet-things`, `hexos-things`) in the local
DB. Otherwise the Portal "discovers" them at
boot and opens a secondary connection to the
remote anyway. After deletion, a fresh boot
log shows `Trying PostgreSQL at localhost ✓`
and NOTHING else. ## Why the data layer alone
wasn't enough Portal boot is Thing-driven: it
reads db-target Things to decide connections.
But there is a **hardcoded fallback** in
`db/mod.rs:177-200` — for any node whose
hostname isn't "hexlet", it does
`hosts.push("hexlet")` (hexlet-first for
non-sovereign, localhost-first for sovereign).
It's bypassed once local db-targets are
discovered, but it remains a hardcoded tendril
(same family as the WITNESS/ARCHITECT crown
constants) that should eventually be
config/sovereignty-driven instead of a literal
"hexlet". ## Result (hexperiment, Day 00357)
Own Linux binary (incl. the new `▲ fid gap
priority` command) · own local Postgres (120k
Things) · `HEXCRAFT_NODE_ID=hexperiment` ·
db-targets = localhost only · pm2 config at
`~/.pm2/hexos-portal.config.js` with a
commented `HEXCRAFT_DB_HOST` toggle for
reference. The boot is data, not config —
which is why the fix lived in Things + one env
flag, not in code.
△