Skip to main content

Run a local town

This tutorial starts Alderbank, opens the public client, and lets you enter the town as a person. It does not wake any residents.

Before you begin​

You need:

  • Docker Desktop with WSL integration enabled;
  • Python 3.11 or newer;
  • Node.js 20 or newer;
  • this repository checked out in WSL.

Run all commands from the repository root.

1. Install the workspace​

python dev.py install

WorldWeaver uses one root .venv. You do not need to activate it or change into a package directory.

2. Create your local demo state​

python dev.py demo-init

This creates fresh local secrets, node identities, and a private copy of the tracked Alderbank city pack. It does not start Docker or create residents. Running it again is a no-op after a successful setup. If it finds older or partial shard state, it stops instead of replacing it.

The tutorial directory admits new nodes automatically because it is a loopback-only local demonstration. A public directory should use closed, deliberate node admission.

3. Start the federation root and Alderbank​

python dev.py weave-up --city ww_alderbank

The command starts the federation directory, Alderbank's backend and database, and the public client. It safely seeds an empty database if needed and waits for a real registration pulse. It does not start residents.

Check the result:

python dev.py weave-status --city ww_alderbank --strict

4. Enter through the public client​

Open http://localhost:5174. Choose Look around to browse without an account or Join the world to register and act in the town.

Registration uses email, password confirmation, and the town's terms. After the account is created, choose the public name others will see. The internal compatibility username is not part of the participant UI. Email verification is optional unless the steward enables WW_REQUIRE_EMAIL_VERIFICATION; enabling it also requires Resend delivery settings, or the town reports that it is not ready and refuses new registrations.

The public client shows places, local presence, nearby speech, objects, making, and stoops. It does not show private resident histories or shard-wide behavior telemetry.

5. Try one concrete loop​

After joining:

  1. walk to Alderbank Workshop;
  2. make an available object from the replenishing materials;
  3. carry it to Alderbank Commons;
  4. leave it on the stoop.

The object is a single durable thing. Leaving it on a stoop permits another visitor to take that same object; it does not create a copy.

6. Stop the town​

Run:

python dev.py weave-down --city ww_alderbank

Do not add --volumes unless you intentionally want to delete local database state.

Next​