Skip to main content

​
Run the project (Windows)

The supported Windows path is WSL 2 with Docker Compose. Docker Desktop’s WSL 2 backend integrates the docker and docker compose CLIs into your Ubuntu shell, and the node treats your WSL distro as a normal Linux host.

​
Prerequisites

  • Windows 10 (with the WSL2 update package) or Windows 11
  • WSL 2 with an Ubuntu distro — see the WSL 2 setup guide
  • Docker Desktop with the WSL 2 based engine enabled and WSL Integration turned on for your Ubuntu distro
  • git (already present in Ubuntu)
Verify inside the Ubuntu (WSL 2) shell:
Use docker compose (with a space). The legacy hyphenated docker-compose is the deprecated Python script and is not supported.

​
Step 1 — Enable Docker Desktop WSL 2 integration

  1. Open Docker Desktop → Settings.
  2. Under General, enable Use the WSL 2 based engine.
  3. Under Resources → WSL Integration, enable integration and toggle on your Ubuntu distro.
  4. Click Apply & Restart.

​
Step 2 — Three-step quickstart inside WSL 2

Open the Ubuntu shell and run:
The first run pulls images and builds the node container, which can take a few minutes. Subsequent starts are near-instant. When the stack is healthy (browse from Windows; ports forward through Docker Desktop):
  • Node RPC: http://localhost:53550 — try curl http://localhost:53550/info from the WSL shell
  • Grafana: http://localhost:3000 (default admin / demos)
  • Prometheus: http://localhost:9091
Clone the repo inside the WSL 2 filesystem (e.g. ~/node), not under /mnt/c/.... WSL 2’s Linux filesystem is dramatically faster for builds and Docker bind mounts than the Windows-mounted drive.

​
Step 3 — Tour of .env

.env.example is the canonical template. The defaults work for local development. The variables you are most likely to touch: Leave PG_HOST=postgres and TLSNOTARY_HOST=tlsnotary exactly as shipped — those are the in-network service names used by docker compose.
Old docs referenced RPC_FEE=5 and SERVER_PORT. Both are wrong. The current names are RPC_FEE (default 1, plus NETWORK_FEE=1 and BURN_FEE=1) and RPC_PORT.

​
Common operations (run from the WSL shell)

State persists in named Docker volumes prefixed demos_ (e.g. demos_node_state holds .demos_identity). Docker Desktop manages the volumes — they survive docker compose down but not docker compose down -v.

​
Going public

If you want peers to reach a node hosted on a Windows machine, you’ll need to forward the relevant inbound TCP ports through both the Windows Defender Firewall and your router (and set EXPOSED_URL to your public address) before advertising the URL:
  • 53550 — Node RPC
  • 53551 — OmniProtocol
  • 7047 — TLSNotary (only if enabled)
For production deployments, a Linux VPS is strongly preferred over a desktop Windows host.

​
Troubleshooting

If you hit an issue, see the dedicated Issue Troubleshooting page.

​
Track 2: Bare metal with ./run (advanced)

Track 2 runs the node binary natively via Bun inside WSL 2 and uses Docker only for a Postgres sidecar managed by the ./run script. Pick this path only for core development, kernel-level debugging, or TUI-driven operation. Do not run Track 2 from Windows directly — always use the Ubuntu shell inside WSL 2. The full walkthrough — Bun via Mise (or the direct installer), Rust for wstcp, ./scripts/install-deps.sh, ./run flags — lives in the source of truth: For the bare-metal path, override these in your .env:
  • PG_HOST=localhost
  • PG_PORT=5332
  • TLSNOTARY_HOST=localhost