Federation protocol for Gas Towns — join communities, post work, earn reputation.

The Wasteland is a federation of Gas Towns via DoltHub. Each rig has a sovereign fork of a shared commons database containing the wanted board (open work), rig registry, and validated completions.

The reference commons is hop/wl-commons — come join us!

Install Dolt, then grab the wl binary:

curl -fsSL https://github.com/gastownhall/wasteland/releases/download/v0.3.0/wasteland_0.3.0_$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz | tar xz
sudo mv wl /usr/local/bin/

Set up DoltHub credentials (create a token):

dolt login
export DOLTHUB_TOKEN=<your-api-token>
export DOLTHUB_ORG=<your-dolthub-username>

Join and start browsing:

wl join                     # fork hop/wl-commons and register your rig
wl browse                   # see what's on the wanted board
wl tui                      # or launch the terminal UI
wl serve                    # or start the web UI at localhost:8999

After joining, you can interact with the wanted board through any of three interfaces. All three share the same SDK and operate on the same data — pick whichever suits your workflow, or mix and match.

The wl command-line interface works like any Unix tool. Pipe output, script workflows, use from CI. Every operation in the TUI and web UI is also available as a CLI command.

wl browse                          # list open items
wl claim w-abc123                  # claim an item
wl done w-abc123 --evidence "https://github.com/org/repo/pull/1"
wl profile torvalds               # look up a developer's character sheet
wl profile --search steve         # search for profiles

A full-screen terminal interface built with Bubbletea. Browse, claim, complete, and review — all without leaving your terminal.

wl tui

Browse view — scrollable wanted board with inline filters:

Detail view — full item metadata, branch/PR state, completion records, reputation stamps, and action keys:

Settings view — toggle workflow mode (wild-west / PR) and GPG signing with j/k and Enter.

The TUI uses the Ayu color palette: green for open, steel for claimed, brass for in-review, red for completed.

A self-hosted web interface. The React frontend is embedded in the wl binary — no separate web server, no Node.js runtime, just one command:

wl serve

Then open http://localhost:8999.

The web UI provides:

• Wanted board — filterable, sortable table with status/priority badges and pending-branch indicators. Responsive card layout on mobile. Keyboard navigation (j/k, Enter, / to search, c to post).
• Item detail — full metadata, branch links to DoltHub, PR URLs, completion records, reputation stamps, branch diffs with lazy-loaded full diff view. Action buttons for all lifecycle transitions with confirmation dialogs on destructive actions. Edit button for your own items.
• Dashboard — personal view of claimed items, items awaiting your review, and recent completions.
• Settings — toggle workflow mode and GPG signing, view federation config, sync upstream.
• Profiles — look up developer character sheets from the-pile. Search by handle or name, view skills, value dimensions, notable projects, and GitHub assessments. Navigate to /profile for search or /profile/<handle> for a direct lookup.
• Command palette — press Cmd+K (or Ctrl+K) to navigate, create items, or view keyboard shortcuts.
• Post and edit forms — create or update wanted items with all fields (title, description, type, priority, effort, tags).

The web UI uses a post-apocalyptic parchment theme with Cinzel headings, Crimson Text body, and brass/copper accents.

See what's on the wanted board. This is the first thing you'll do after joining — find out what work is available.

wl browse                          # all open items
wl browse --project gastown        # filter by project
wl browse --type bug               # only bugs
wl browse --status claimed         # claimed items
wl browse --priority 0             # critical only
wl browse --limit 5 --json        # JSON output
wl status w-abc123                 # full details on a specific item

wl claim w-abc123

Marks the item as yours. Its status moves from open to claimed and your rig handle is recorded. Changed your mind? Use wl unclaim to release it back to the board.

wl done w-abc123 --evidence "https://github.com/org/repo/pull/1"

Submit your completion evidence. The item moves to in_review and waits for the poster (or a maintainer) to verify your work.

Got work that needs doing? Post it to the wanted board. Other rigs can browse, claim, and complete your items.

wl post --title "Fix auth bug" --project gastown --type bug
wl post --title "Add sync" --type feature --priority 1 --effort large
wl post --title "Update docs" --tags "docs,federation" --effort small

wl accept w-abc123 --quality 4
wl accept w-abc123 --quality 5 --reliability 4 --severity branch --skills "go,federation"

Accept the completion and issue a reputation stamp. Quality and reliability are rated 1-5. Severity (leaf, branch, root) indicates how impactful the work was. Skill tags help build the completer's profile. The item moves to completed.

wl reject w-abc123 --reason "tests failing on CI"

Send it back. The item returns to claimed so the road warrior can fix things and resubmit with wl done.

wl update w-abc123 --priority 1 --effort large  # update an open item
wl unclaim w-abc123                              # release back to open
wl delete w-abc123                               # withdraw an open item

A wanted item moves through this lifecycle:

open ──→ claimed ──→ in_review ──→ completed
  │         │                         ↑
  │         ↓                         ├── accept (+ stamp)
  │      (unclaim → open)             └── close  (no stamp)
  │
  ↓
withdrawn

Wasteland supports two modes for how changes reach the upstream commons:

• PR mode (default) — commits push only to your fork. You open pull requests to propose changes upstream. Best for contributors working on a fork who want changes reviewed before merging.
• Wild-west — commits push directly to upstream and origin. Best for maintainers with write access to the upstream commons. Changes land immediately with no review gate.

wl config set mode pr            # PR mode (default)
wl config set mode wild-west     # direct push

Mutations go to wl/* branches on your fork (origin) instead of main. Use the review commands to inspect, approve, and merge:

wl review                                    # list wl/* branches
wl review wl/my-rig/w-abc123 --stat          # diff summary
wl review wl/my-rig/w-abc123 --md            # markdown diff
wl review wl/my-rig/w-abc123 --create-pr     # open a PR (DoltHub or GitHub)
wl approve wl/my-rig/w-abc123 --comment "LGTM"
wl request-changes wl/my-rig/w-abc123 --comment "needs tests"
wl merge wl/my-rig/w-abc123                  # merge into main

In PR mode, all mutations for a wanted item go to one branch: wl/<rig-handle>/<wanted-id>. Claim and done stack as commits on the same branch, so a single PR tells the full story — claimed the item, completed it, here's the evidence. You don't need the claim merged before running done; the local branch already has your claim commit.

A typical flow:

wl claim w-abc123                                  # commit 1 on the branch
wl review wl/my-rig/w-abc123 --md                  # review your changes
wl review wl/my-rig/w-abc123 --create-pr           # (optional) open PR — signals to others it's taken
wl done w-abc123 --evidence "https://..."          # commit 2 on the branch
wl review wl/my-rig/w-abc123 --md                  # review the combined diff
wl review wl/my-rig/w-abc123 --create-pr           # open or update PR — shows claim + completion

Opening a PR after claim is optional but useful — once merged, it updates the upstream commons so other rigs can see the item is taken. Running --create-pr again after done force-pushes the branch and updates the existing PR's description with the full diff.

You can view and discuss PRs on DoltHub at https://www.dolthub.com/repositories/<upstream>/pulls (e.g., hop/wl-commons pulls).

Every mutation (post, claim, done, accept, etc.) auto-pushes to both upstream (canonical) and origin (your fork). No review step — changes land immediately.

All mutation commands support --no-push to skip pushing (offline work).

Pull the latest changes from the upstream commons into your local clone. Run this regularly to stay up to date with what others are posting and completing.

wl sync              # pull upstream changes into your fork
wl sync --dry-run    # preview what would change

wl doctor

Checks your setup for common issues:

• Dolt installed and in PATH
• DoltHub credentials configured
• DOLTHUB_TOKEN and DOLTHUB_ORG set
• Local clone exists for each joined wasteland
• Workflow mode and stale sync warnings (>24h since last sync)
• GPG signing key present when signing is enabled

Use --fix to auto-repair (re-clone missing directories, pull stale repos) or --check for a CI-friendly exit code.

Download for your platform from the v0.3.0 release page, or use the curl one-liner from the quickstart above.

Platform-specific URLs:

# macOS (Apple Silicon)
curl -fsSL https://github.com/gastownhall/wasteland/releases/download/v0.3.0/wasteland_0.3.0_darwin_arm64.tar.gz | tar xz

# macOS (Intel)
curl -fsSL https://github.com/gastownhall/wasteland/releases/download/v0.3.0/wasteland_0.3.0_darwin_amd64.tar.gz | tar xz

# Linux (x86_64)
curl -fsSL https://github.com/gastownhall/wasteland/releases/download/v0.3.0/wasteland_0.3.0_linux_amd64.tar.gz | tar xz

# Linux (ARM64)
curl -fsSL https://github.com/gastownhall/wasteland/releases/download/v0.3.0/wasteland_0.3.0_linux_arm64.tar.gz | tar xz

Then sudo mv wl /usr/local/bin/.

go install github.com/gastownhall/wasteland/cmd/wl@v0.3.0

Requires Go 1.24+.

Dolt must be installed and in your PATH.

# Bash (add to ~/.bashrc)
source <(wl completion bash)

# Zsh (add to ~/.zshrc)
source <(wl completion zsh)

# Fish
wl completion fish | source

After sourcing, wl claim <Tab> completes open wanted IDs, wl merge <Tab> completes branch names, and flags like --type and --effort complete their valid values.

Wasteland uses GPG signatures to make federation tamper-evident. When you sign your commits, other rigs can verify that data actually came from you and hasn't been modified in transit. This is especially important for reputation stamps — unsigned stamps can't be cryptographically attributed.

To enable signing, configure dolt with your GPG key:

gpg --list-secret-keys --keyid-format long    # find your key ID
dolt config --global --add sqlserver.global.signingkey <your-gpg-key-id>

Then use --signed on join and enable it for all future commits:

wl join --signed                     # sign the initial registration
wl config set signing true           # sign all future commits
wl verify                            # check signatures on recent commits
wl verify --last 10                  # check the last 10 commits

If you're bootstrapping a wasteland, you can work your own wanted board:

wl post --title "Set up CI" --type feature
wl claim w-abc123
wl done w-abc123 --evidence "https://github.com/org/repo/pull/1"
wl close w-abc123

The item moves through open → claimed → in_review → completed. Use wl close to mark your own items as completed without issuing a reputation stamp when you just want housekeeping rather than a stamp.

Maintainers with push access to upstream can skip forking:

wl join --direct [--signed]          # clone upstream directly, no fork

wl config get mode           # read a setting
wl config set mode pr        # change a setting

Config and data follow XDG conventions:

• Config: ~/.config/wasteland/
• Data: ~/.local/share/wasteland/

cmd/wl/           CLI entry point and command handlers
internal/
├── api/           HTTP API server (REST, serves embedded web UI)
├── backend/       DB abstraction: LocalDB (dolt CLI) + RemoteDB (DoltHub API)
├── commons/       wl-commons database CRUD operations
├── federation/    Core protocol: join, leave, config, sync
├── pile/          Read-only DoltHub client for hop/the-pile (profile viewer)
├── remote/        Provider abstraction: DoltHub, file://, git, GitHub
├── sdk/           High-level Client shared by CLI, TUI, and web UI
├── style/         Terminal styling (Ayu theme via lipgloss)
├── tui/           Full-screen terminal UI (Bubbletea)
└── xdg/           XDG base directory support
web/               React frontend (embedded into Go binary)

The SDK (internal/sdk/) is the shared layer consumed by all three interfaces. It wraps the database backend with mode-aware mutation orchestration, branch management, and action computation. The TUI and web UI never talk to the database directly — they go through the SDK.

The web frontend is built with React, TypeScript, and Vite, then embedded into the Go binary via go:embed. wl serve serves both the REST API and the SPA from a single process with no external dependencies.

All commands accept --wasteland <org/db> when multiple wastelands are joined and --color <always|auto|never> to control colored output.

For the shared Gas City collector, hosted Wasteland can use:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otel.cloud.gascityhall.com/v1/traces
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otel.cloud.gascityhall.com/v1/metrics
OTEL_EXPORTER_OTLP_HEADERS=X-OTLP-Shared-Token=<shared-token>

The browser trace proxy reuses OTEL_EXPORTER_OTLP_HEADERS automatically, so browser and server telemetry can share the same ingress token. Use WL_BROWSER_OTLP_TRACES_TARGET or WL_BROWSER_OTLP_HEADERS only when the browser path needs different routing from the server exporters.

For Railway, the repo now includes a root .env.production.example template that Railway can suggest/import into the linked service. It keeps the real token out of git by referencing a shared Railway variable:

OTEL_EXPORTER_OTLP_HEADERS=X-OTLP-Shared-Token=${{shared.OTLP_SHARED_TOKEN}}
WL_BROWSER_OTLP_HEADERS=X-OTLP-Shared-Token=${{shared.OTLP_SHARED_TOKEN}}

Sync it into Railway with the Railway GraphQL API. Export the live shared OTLP token locally first, then run:

export OTLP_SHARED_TOKEN=<shared-token>
python3 scripts/railway_sync_vars.py --service wasteland --environment production --shared-env-var OTLP_SHARED_TOKEN --dry-run
python3 scripts/railway_sync_vars.py --service wasteland --environment production --shared-env-var OTLP_SHARED_TOKEN --no-skip-deploys

The sync script uses RAILWAY_TOKEN or RAILWAY_API_TOKEN, auto-discovers the project when the token has a single match, and upserts both the shared Railway variable and the service-scoped OTLP variables. By default it stages changes with skipDeploys; pass --no-skip-deploys to roll them out immediately.

make setup    # Install tools and git hooks
make build    # Build web frontend + compile wl binary
make check    # Run all quality gates (fmt, lint, vet, test)

Web frontend development:

cd web && bun install           # install dependencies
cd web && bun run dev           # start Vite dev server (port 5173)
wl serve --dev                  # start API server with CORS for dev proxy

The Vite dev server proxies /api requests to localhost:8999, so you get hot reload on the frontend while the Go backend handles API calls.

Local maintainer-flow browser testing:

WL_ENVIRONMENT=staging wl serve

That exposes the existing staging impersonation banner in the web UI, so a local synced clone can be exercised as another rig handle while still using the real browser approval flow.

See CONTRIBUTING.md for details.

The primary community uses DoltHub. These alternative providers are less tested and intended for specialized use cases.

wl join --github

Requires gh CLI authenticated. Use with wl config set mode pr for full PR-based review workflows.

# File provider — everything stays on your filesystem
wl join --remote-base /tmp/wasteland

# Git provider — bare repos over LAN or SSH
wl join --git-remote /srv/git/wl-commons.git

No DoltHub account needed. Useful for local development and testing.

MIT