> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wrapper.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Run Wrapper from source and verify the local stack.

## Prerequisites

* Bun 1.3.5 or newer
* macOS or Linux
* A Convex development deployment

Clone the repository and initialize its mobile submodule:

```bash theme={null}
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:

```bash theme={null}
make -C apps/mobile bootstrap
```

Then install the Bun workspace from the repository root:

```bash theme={null}
bun install
```

## Start the services

Run each command in a separate terminal.

Backend:

```bash theme={null}
cd packages/backend && bunx convex dev
```

Relay (point at your Convex `.cloud` URL):

```bash theme={null}
cd apps/relay
CONVEX_URL="https://<your-dev>.convex.cloud" bun run dev
```

Web:

```bash theme={null}
cd apps/web && bun run dev
```

CLI host:

```bash theme={null}
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:

```bash theme={null}
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`](https://github.com/heycupola/wrapper/blob/main/ENVIRONMENTS.md).

## Local quality checks

```bash theme={null}
bun run lint
bun run format:check
bun run check-types
bun run audit
bunx turbo run test
```

Docs:

```bash theme={null}
bun run --cwd apps/docs build
bun run --cwd apps/docs dev
```

## Relay smoke check

```bash theme={null}
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

1. `NODE_ENV=development wrapper auth login` (or the source CLI equivalent)
2. Start a host and share with `Ctrl+\` then `s`
3. Attach from another terminal with `--relay --id <sessionId>`
4. Detach with `Ctrl+\` then `d`
5. Unshare with `Ctrl+\` then `u`
6. Watch the title for `relay` then optionally `p2p`
7. 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.