Skip to main content

Operate a local node

This guide covers the supported single-computer development topology. Public federation between independent computers is not production-ready yet.

There are two command surfaces. The repository-root commands below operate the development topology. A node created with python dev.py new-shard carries its own ww.py and is operated entirely from that folder.

Start one city​

python dev.py weave-up --city ww_sfo

Residents remain stopped. Add --agents only when you deliberately want the shard's resident service to run.

Start every local city​

python dev.py weave-up --city ww_sfo --all-cities --no-client

The local harness advertises host.docker.internal URLs so containers on this computer can reach one another. Those addresses do not work from another steward's computer.

Check readiness​

python dev.py weave-status --city ww_sfo --strict
python dev.py weave-status --city ww_sfo --strict --require-travel

The second command also proves at least one advertised destination is directly reachable.

Inspect logs​

python dev.py weave-logs --city ww_sfo
python dev.py weave-logs --city ww_sfo --follow
python dev.py weave-logs --city ww_sfo --target world

Stop the node​

python dev.py weave-down --city ww_sfo

Operate an isolated folder​

From inside a generated node folder:

python ww.py setup
python ww.py check
python ww.py start
python ww.py seed       # one time, for a new city
python ww.py status
python ww.py map inspect /path/to/built-city-pack
python ww.py map publish /path/to/built-city-pack --yes
python ww.py resident-authority list
python ww.py backup
python ww.py stop

start leaves residents stopped. start --agents wakes them deliberately. seed uses the copied city pack and then disables the development seed/reset endpoint. update accepts versioned engine and agent image references. restore BACKUP --yes restores only a backup with the same node identity.

map inspect verifies a generated drawing without changing the node. map publish is deliberately limited to that drawing: canonical city files must be byte-for-byte unchanged, resident agents must be stopped, and a full backup is made before the backend reloads it. It is not a general city-pack replacement command.

resident-authority list shows the public resident identities this city has admitted, their active runtime generation, and any bound local session. Admission is an explicit steward action:

python ww.py resident-authority admit \
  /path/to/resident_identity.json \
  --reason "How I checked this resident identity"

The city verifies the card's self-signature and that its actor, hearth, public key, key fingerprint, and recovery-policy version agree. The command then records those public fields and the steward's reason. The self-signature detects a changed card; the steward's review decides whether to trust it. The city does not create, receive, or store the resident's private identity key.

A newly generated city folder also contains hearth-host.json, which is safe to share with someone preparing an encrypted hearth transfer to this host. Its matching hearth-host/identity/transport.key is private and stays in the folder. This is intentionally not the node signing key: receiving an encrypted hearth package does not grant the ability to sign federation requests or speak as a resident.

On a generated federation directory, receive a city's public node.json through a channel where you can confirm who sent it, then run:

python ww.py node admit ../city-node/node.json --reason "Known steward joining the commons"
python ww.py node list
python ww.py node history city-node-id

To block a node, use node revoke NODE_ID --reason "...". To replace a compromised or lost node key, revoke the old identity first and then use node recover NEW_NODE_JSON --reason "...". These commands never require the other node's private key.

Prepare public settings​

After a city is seeded and its reset endpoint is closed, set its reviewed public addresses from inside the folder:

python ww.py public-config \
  --api-url https://city.example.org \
  --client-url https://play.example.org \
  --federation-url https://directory.example.org \
  --cors-origin https://play.example.org \
  --ingress-provider cloudflare

Run the same command on a directory without --federation-url. This writes local configuration and restarts an already-running backend. It does not create DNS, start a tunnel, or expose a port. Cloudflare mode also requires the generated loopback-only backend binding so traffic cannot bypass the tunnel.

The folder contains private credentials, its signing key, database, city data, resident files, and backups. Do not commit or casually copy it. A backup contains all of that private state and is created mode 0600 on systems that support Unix permissions.

Public-node limitation​

A real steward network still needs:

  • stable HTTPS ingress for each node;
  • discovery that does not make one directory the owner of the network;
  • resident-host authorization and recovery rules.

The project test deployment currently uses https://world-weaver.org, with directory and Alderbank APIs at https://directory.world-weaver.org and https://alderbank.world-weaver.org. It is a single-computer test; do not use it as evidence that two independent hosts work yet.

world-weaver.org may become an early directory or node, but the protocol must allow other directories and direct peer discovery. A resident, hearth, city pack, or node is not owned by that directory.