Harbor for developers

Build the system, not just the happy path

Harbor combines a React and TypeScript interface, a Rust and Tauri backend, libp2p application networking, WebRTC media, local SQLite state, and a standalone relay. This guide gets a contributor from clone to a meaningful multi-profile test.

System model

Local identity

Ed25519 signing and X25519 agreement keys are encrypted on disk. SQLite is the local source of truth.

App networking

libp2p handles discovery, direct connections, relay circuits, signaling, messages, and synchronization.

Call media

WebRTC transports audio and video. STUN and TURN solve media connectivity and are separate from the Harbor relay.

Permissions

Signed capability grants control Chat, Call, and WallRead behavior between identities.

Diagram needed: 11-system-architecture.pngTwo Harbor clients, local SQLite on each, direct or libp2p relay application path, and separate direct or TURN WebRTC media path.

Keep the application relay and media relay visually separate. They solve different problems.

Local development setup

Prerequisites

Node.js 20 or newer and pnpm 10.
Stable Rust and Cargo.
Tauri 2 operating-system prerequisites.
GitHub CLI for the pull-request workflow.

git clone https://github.com/Bakobiibizo/harbor.git
cd harbor
pnpm install
pnpm tauri dev

Use the repository's .dev/bin/dev commands for CI-equivalent installation and checks where documented. Do not weaken updater signing or security gates to make a local build pass.

Screenshot needed: 12-dev-first-run.pngTerminal with pnpm tauri dev ready, next to a disposable Harbor development window.

Use a disposable identity and redact home-directory paths if the screenshot will be public.

Run isolated profiles

Most production behavior requires at least two real app profiles. Unit tests and mocked stores do not prove identity, transport, persistence, or WebRTC convergence.

Create separate data directories and profile names for each app instance.
Create disposable identities in both profiles.
Start networking and exchange contact links.
Exercise the workflow from both perspectives.
Record timestamps and observable state transitions without recording secrets.

Use the repository validation guides for the exact environment variables and evidence requirements:

docs/voice-call-e2e-validation.md
docs/video-group-call-validation.md
docs/wall-sync-multi-profile-validation.md

Screenshot needed: 13-two-profile-lab.pngTwo app windows labeled dev-a and dev-b, both connected, with no personal identities.

A useful development screenshot makes each profile and network state unambiguous.

Relay and TURN operations

Do not conflate the relays: the Harbor libp2p relay carries application traffic and call signaling. A TURN server relays WebRTC media when direct ICE connectivity fails.

cargo build --manifest-path relay-server/Cargo.toml
HARBOR_RELAY_DB=/tmp/harbor-relay.sqlite \
  cargo run --manifest-path relay-server/Cargo.toml -- \
  --listen /ip4/127.0.0.1/tcp/4001

Copy the printed relay multiaddress into each disposable profile. For strict-NAT media tests, configure an operator-managed TURN service in Settings, Calls. Never commit or screenshot TURN credentials.

Screenshot needed: 14-network-operator-view.pngHarbor Network settings with a redacted relay multiaddress and healthy state.

Redact private hosts and credentials. Peer IDs are public identifiers but should still use disposable test profiles.

Run validation gates

pnpm exec tsc --noEmit
pnpm exec vitest run
cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --all-targets
cargo test --manifest-path relay-server/Cargo.toml

Also run the focused manual scenario for the capability you changed. A calling change needs two-profile media evidence. A wall permission change needs authorized and unauthorized consumers. A release change needs packaged artifacts, updater metadata, and platform smoke tests.

Contribution workflow

main is protected production code. Direct pushes, force-pushes, and deletion are blocked.

git switch main
git pull --ff-only
git switch -c feature/short-description

# make and validate a focused change
git add path/to/intended/files
git commit -m "Describe the focused change"
git push -u origin feature/short-description
gh pr create --draft --fill

Keep one coherent concern per branch.
Explain user impact, root cause, validation, and known limitations in the PR.
Use the preview build for UI review.
Resolve review conversations and keep the branch current with main.
Merge only after every required check is green.

Release discipline

Production releases originate from protected, reviewed history.
Version and updater metadata must agree.
Every updater artifact requires a nonempty signature and public URL.
Windows, macOS Intel, macOS Apple Silicon, and Linux packaging must complete before platform claims are published.
Do not replace live-network evidence with screenshots or unit tests.

See docs/release-gates-calls-wall-sync.md and docs/demo-operations.md in the Harbor repository for current operational gates.

Share diagnostics safely

Useful in a bug report

Harbor version, operating system, architecture, and installation type.
The exact workflow step and expected versus actual behavior.
Connection and call state names with approximate timestamps.
Disposable profile peer IDs when necessary to correlate a test.
Minimal logs reviewed for private content.

Never publish

Passphrases, private keys, identity exports, or database files.
TURN passwords or long-lived infrastructure credentials.
Private message bodies, media, or contact links from real users.
Unredacted IP addresses unless explicitly required in a private security report.

Start with a bounded change

Read CONTRIBUTING.md, select an issue with a clear acceptance test, and open a draft PR early. Security vulnerabilities should be reported privately rather than filed with exploit details in a public issue.