Skip to main content

Getting Started

This guide gets you from clone to a verified local session quickly.

Goal​

By the end of this page, you should have:

  1. gateway container running and healthy
  2. optional relay container running
  3. host/client runtimes started
  4. a basic session validated

Prerequisites​

Required:

  • Rust 1.75+
  • protobuf-compiler
  • pkg-config

Optional:

  • Bun (desktop app)
  • Android SDK/NDK (Android builds)
  • Xcode (macOS packaging)

Linux note:

  • For Wayland hosts, ensure PipeWire + XDG portal stack is installed.
  • Use Linux and Wayland Support for distro-specific setup.

1. Clone and Build​

git clone https://github.com/bybrooklyn/wavry.git
cd wavry
cargo build --workspace --locked

Expected outcome:

  • Workspace compiles successfully with no build errors.

2. Start Control Plane (Docker-Only)​

Start gateway:

docker compose -f docker/control-plane.compose.yml up -d gateway

Verify gateway health:

curl -fsS http://127.0.0.1:3000/health

If you want relay fallback validation, start relay profile:

WAVRY_RELAY_MASTER_URL=http://host.docker.internal:8080 \
docker compose -f docker/control-plane.compose.yml --profile relay up -d relay

Check container status:

docker compose -f docker/control-plane.compose.yml ps

3. Start Host and Client Runtimes​

Terminal A (host):

RUST_LOG=info cargo run --bin wavry-server

Terminal B (client):

RUST_LOG=info cargo run --bin wavry-client

Expected outcome:

  • Host and client start without panic.
  • Client reaches connected/active state when target is resolved.

4. Validate Basic Session Quality​

Confirm:

  • input feels responsive
  • no repeated handshake failures in logs
  • no runaway delay growth under short interaction bursts

Useful checks:

# control plane health
curl -fsS http://127.0.0.1:3000/health

# control plane container logs
docker compose -f docker/control-plane.compose.yml logs --tail=100 gateway

5. Optional Desktop App Run​

cd crates/wavry-desktop
bun install
bun run tauri dev

Then use desktop UI for host/client workflow testing.

Run preflight:

./scripts/linux-display-smoke.sh

If preflight fails, follow Linux and Wayland Support.

Common First-Run Problems​

Gateway is unhealthy​

  • Check container logs: docker compose -f docker/control-plane.compose.yml logs gateway
  • Confirm 3000 is not already in use.

Client cannot connect​

  • Confirm host runtime is active.
  • Confirm target/session settings are correct.
  • Confirm firewall policy permits required UDP path.

Session is unexpectedly relayed​

  • Recheck NAT/firewall behavior.
  • Confirm direct candidate path availability.

Linux capture fails​

  • Run ./scripts/linux-display-smoke.sh.
  • Verify portal backend packages and PipeWire availability.

Teardown​

Stop local control-plane containers:

docker compose -f docker/control-plane.compose.yml down

Stop host/client runtimes with Ctrl+C in their terminals.

Next Steps​

  1. Architecture
  2. Session Lifecycle
  3. Docker Control Plane
  4. Security
  5. Operations
  6. Troubleshooting