ar.io DocumentationQuick Start
Get your Wayfinder Router running in 30 seconds. No configuration needed - the admin UI wizard will guide you through setup.
Quickstart
Download the latest binary for your platform from GitHub Releases:
| Platform | Binary |
|---|---|
| Linux x64 | wayfinder-router-linux-x64 |
| Linux ARM64 | wayfinder-router-linux-arm64 |
| macOS Intel | wayfinder-router-darwin-x64 |
| macOS Apple Silicon | wayfinder-router-darwin-arm64 |
| Windows x64 | wayfinder-router-windows-x64.exe |
Each release includes checksums.txt with SHA256 hashes for verification.
Download and make executable
# Download (example for Linux x64)
curl -LO https://github.com/ar-io/wayfinder-router/releases/latest/download/wayfinder-router-linux-x64
# Make executable
chmod +x wayfinder-router-linux-x64
# Verify checksum (optional but recommended)
sha256sum wayfinder-router-linux-x64Run
./wayfinder-router-linux-x64The admin UI automatically opens at http://localhost:3001 with a setup wizard.
Test
# Fetch a test transaction
curl http://localhost:3000/4jBV3ofWh41KhuTs2pFvj-KBZWUkbrbCYlJH0vLA6LM
# Expected output: testRun with Docker
docker run -p 3000:3000 -p 3001:3001 ghcr.io/ar-io/wayfinder-router:latestOr with Docker Compose (uses ports 3020/3021 by default):
git clone https://github.com/ar-io/wayfinder-router
cd wayfinder-router
docker compose up -dOpen Admin UI
Navigate to http://localhost:3001 in your browser. The setup wizard will guide you through configuration.
Test
curl http://localhost:3000/4jBV3ofWh41KhuTs2pFvj-KBZWUkbrbCYlJH0vLA6LM
# Expected output: testProduction Docker:
docker run -p 3000:3000 -p 3001:3001 \
--env-file .env \
-v ./data:/app/data \
ghcr.io/ar-io/wayfinder-router:latestThe ./data volume persists telemetry, content cache, and blocklist data.
Requires Bun >= 1.0.0.
Clone and install
git clone https://github.com/ar-io/wayfinder-router
cd wayfinder-router
bun installConfigure (optional)
cp .env.example .env
# Edit .env as needed, or skip and use the setup wizardRun
# Development with hot reload
bun run dev
# Production
bun run startThe admin UI opens at http://localhost:3001.
Build standalone binaries:
bun run build:binaries # outputs to ./builds/Setup Wizard
On first run (when BASE_DOMAIN=localhost), the admin UI shows a guided setup wizard:
Domain Configuration
Configure your base domain, port, and optional root host content. For local development, keep the defaults.
Routing Settings
Choose your operating mode and routing strategy:
| Setting | Options | Recommended |
|---|---|---|
| Mode | proxy or route | proxy for full verification |
| Strategy | fastest, random, round-robin, temperature | temperature for production |
| Gateway Source | network, trusted-peers, static | network for full decentralization |
Verification Settings
Enable content verification and configure trust settings:
| Setting | Default | Description |
|---|---|---|
| Enabled | true | Verify content hashes before serving |
| Trust Source | top-staked | Use top-staked gateways for verification |
| Gateway Count | 3 | Number of gateways to query |
| Consensus | 2 | Minimum gateways that must agree |
Save Configuration
The wizard generates a .env file. You can copy it to clipboard or save directly to the server.
Accessing Content
Once running, access Arweave content through your router:
# By transaction ID
http://localhost:3000/{txId}
http://localhost:3000/{txId}/path/to/file
# By ArNS name (subdomain)
http://{arns-name}.localhost:3000/
http://{arns-name}.localhost:3000/path/to/fileServing Content at Root Domain
Configure ROOT_HOST_CONTENT to serve an ArNS name or transaction ID at your root domain:
# In .env
ROOT_HOST_CONTENT=wayfinder
# Or a transaction ID
ROOT_HOST_CONTENT=bNbA3TEQVL60xlgCcqdz4ZPHFZ711cZ3hmkpGttDt_UWith this configuration:
https://yourdomain.com/serves the configured contenthttps://yourdomain.com/docsserves the/docspath within that contenthttps://yourdomain.com/wayfinder/infostill returns router info
What's Next?
Configuration
Full reference for all environment variables
Admin UI
Monitor gateways, view telemetry, manage moderation
Operations
Production deployment, monitoring, and troubleshooting
How is this guide?