What you get
- MCP Server — an Urbit MCP server that can connect to your AI agent, interact with your urbit, and develop Urbit apps
- SPV Wallet — a Bitcoin light client built into your Urbit ship
- Landscape — Urbit’s home screen with app management, notifications, and settings
- Groups — group chat and channels, hosted on your own machine
- Nostrill — a Nostr client running inside Urbit
Everything runs locally. Your keys never leave your device.
Requirements
- Linux (x86_64 or aarch64) or macOS (Apple Silicon)
- ~2 GB RAM free
- ~1 GB disk space
- An internet connection
- An invite code
Quickstart
Download the latest release for your platform from groundwire.io. The onboarding script walks you through everything:
- Master ticket — A randomly generated passphrase (like
~sampel-palnet-sampel-palnet). This is your login credential and wallet seed. Write it down. If you lose it, you lose access to your ship and your wallet. - Funding — The script derives a Bitcoin address from your ticket and requests coins from our faucet using your invite code. No action needed.
- Comet mining — Your Bitcoin transaction is used to generate a unique Urbit identity (a “comet”). This takes a few minutes.
- Attestation — The script submits your identity to Bitcoin and waits for block confirmations. No action needed.
- Boot — Your ship starts up. The first boot compiles the system and takes several minutes. Subsequent boots are fast.
Once the ship is running, open your browser to the URL shown (usually http://localhost:8080). Log in with your +code — type +code in the dojo (the command line in your terminal) to see it.
After boot
- Wallet:
http://localhost:<port>/spv-wallet— your Bitcoin wallet - Landscape:
http://localhost:<port>/apps/landscape— your home screen - Groups: available through Landscape
- Dojo: the terminal where your ship is running — this is your Urbit command line
Resuming
If you close your ship (Ctrl+C), restart it with:
./gw-vere Where <pier-name> is the directory that was created during boot. By default this will be at ~/.local/share/groundwire-alpha/
If you need to start over, re-run:
./gw-onboard --master-ticket Important notes
- This is alpha software. Identities are not yet guaranteed to be permanent.
- Your master ticket is everything — it derives your wallet keys and is your ship login. Keep it safe.
- This wallet holds real Bitcoin. Treat your master ticket like you would treat your seed phrase.
- First boot takes 5–15 minutes. Be patient.
- The ship stores data in the pier directory. Back it up if you care about your state.
Troubleshooting
- Ship won’t start: Make sure no other Urbit ship is using the same port. Try
./gw-vere <pier> --http-port 8081. - Funding doesn’t arrive: The faucet requires a valid invite code. If automatic funding fails, the script will show the address — you can send Bitcoin to it manually.
- NixOS users: The compiled binary uses dynamic linking that doesn’t work on NixOS. Install Python 3 and run:
pip install -r requirements.txt && python gw-onboard.py