Setup

Prerequisites

Bun 1.3.5 or newer
macOS or Linux
A Convex development deployment

Clone the repository and initialize its mobile submodule:

git clone --recurse-submodules https://github.com/heycupola/wrapper.git
cd wrapper

# For an existing clone:
git submodule update --init --recursive

The parent repository tracks only the mobile commit pointer. Mobile commits belong in the nested repository first. Mobile bootstrap is optional for CLI, backend, relay, and web work. On macOS, after installing the Xcode and XcodeGen versions listed in apps/mobile/README.md, generate the ignored Xcode project:

make -C apps/mobile bootstrap

Then install the Bun workspace from the repository root:

bun install

Start the services

Run each command in a separate terminal. Backend:

cd packages/backend && bunx convex dev

Relay (point at your Convex .cloud URL):

cd apps/relay
CONVEX_URL="https://<your-dev>.convex.cloud" bun run dev

Web:

cd apps/web && bun run dev

CLI host:

NODE_ENV=development \
  WRAPPER_CONVEX_URL="https://<your-dev>.convex.cloud" \
  WRAPPER_RELAY_URL="ws://localhost:8080" \
  WRAPPER_AUTH_ORIGIN="http://localhost:3000" \
  bun run --cwd apps/cli dev:host

For an offline host-only CLI check without the backend or relay:

NODE_ENV=development bun run apps/cli/index.ts shell-host

Released CLI binaries use production endpoints when NODE_ENV is unset. Connected source development must set explicit Convex, relay, and auth URLs. The complete environment and deployment matrix lives in ENVIRONMENTS.md.

Local quality checks

bun run lint
bun run format:check
bun run check-types
bun run audit
bunx turbo run test

Docs:

bun run --cwd apps/docs build
bun run --cwd apps/docs dev

Relay smoke check

RELAY_URL="https://relay.example.com" bun run --cwd apps/relay smoke

This checks relay health and rejects an unauthenticated WebSocket request.

Manual end-to-end check

NODE_ENV=development wrapper auth login (or the source CLI equivalent)
Start a host and share with Ctrl+\ then s
Attach from another terminal with --relay --id <sessionId>
Detach with Ctrl+\ then d
Unshare with Ctrl+\ then u
Watch the title for relay then optionally p2p
Repeat with WRAPPER_P2P=0 and confirm it stays on relay

NAT-restricted networks and CI sandboxes often cannot form WebRTC. Relay-only success is still a valid result.

Getting Started

Guides

Configuration

Development

Reference

Prerequisites

Start the services

Local quality checks

Relay smoke check

Manual end-to-end check

​Prerequisites

​Start the services

​Local quality checks

​Relay smoke check

​Manual end-to-end check

Prerequisites

Start the services

Local quality checks

Relay smoke check

Manual end-to-end check