# Droidex User Setup

This guide is for setting up Droidex so an Android phone can control a Mac Codex app.

## What You Need

- A Mac with Codex installed and working locally.
- An Android phone with the Droidex app installed.
- Internet access on the Mac so the setup can create the accountless Cloudflare Quick Tunnel.
- No Cloudflare account, DNS setup, or manual relay lifecycle management is required for the default path.

Droidex uses two layers:

- Relay token: allows devices to connect to your relay.
- Pairing secret: encrypts Codex traffic end to end between Android and the Mac sidecar.

Treat the QR code, pairing JSON, relay URL, and pairing secret as credentials. The Mac sidecar used by Droidex is JavaScript launched by the skill with Codex's bundled Node runtime, so the default user path does not require Xcode, Swift build tools, or a signed/notarized Mac companion app.

## 1. Install The Droidex Skill

Install the `androidex` skill from the currently published `@thecsguy/androidex` npm package:

```bash
npx -y @thecsguy/androidex@latest install-skill
```

Restart Codex or refresh installed skills if the app asks.

If you are testing from a source checkout before the npm package is published, run:

```bash
npm run install-skill
```

## 2. Install The Android App

Open [droidex.app](https://droidex.app/) on your phone, tap **Download Android APK**, and open the APK. Or install from a source checkout with a connected Android device:

```bash
npm run android:assemble
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```

## 3. Launch Pairing In Codex

Then type this in Codex:

```text
/androidex
```

The skill creates a token-gated loopback relay on the Mac, starts a Cloudflare Quick Tunnel, installs LaunchAgents for the relay, tunnel, and Node sidecar, stores credentials in user-only files, and displays the pairing QR directly in chat. The QR uses a `wss://*.trycloudflare.com` relay URL, so the phone can be on Wi-Fi or cellular and does not depend on mDNS, `.local`, or sharing the Mac's network. The sidecar connects to the local loopback relay through `sidecar-relay-url`, so it does not wait on Cloudflare DNS. The sidecar/tunnel LaunchAgents keep the session alive; if the temporary tunnel URL changes after a full restart, Droidex regenerates the QR.

## 4. Pair Android

1. Open Droidex on Android.
2. Scan the QR shown in the Codex chat after `/androidex`.
3. Droidex saves the pairing and starts loading Mac projects and sessions automatically.

## Optional Stable Relay

The default Quick Tunnel is free and accountless. If you want a stable hostname that survives tunnel URL rotation without rescanning, run a relay on an internet-reachable host with DNS pointed at it:

```bash
export RELAY_DOMAIN="relay.example.com"
export RELAY_TOKEN="$(openssl rand -hex 32)"
npm run relay:docker:run:tls
```

Validate it from a network outside your Mac LAN:

```bash
RELAY_URL="wss://$RELAY_DOMAIN/ws?token=$RELAY_TOKEN" npm run relay:public-smoke
```

Use this relay URL for the Mac sidecar and Android pairing:

```text
wss://relay.example.com/ws?token=...
```

`npm run relay:public-smoke` requires `wss://` relay and `https://` health URLs by default. It also rejects localhost, private IP ranges, `.local`, reserved documentation domains (`.example`, `.test`, `.invalid`), and single-label hosts for both relay and health URLs. Use `--allow-insecure` or `--allow-private-target` only for local/debug relay testing.

Then install using that stable relay:

```text
/androidex --relay "wss://relay.example.com/ws?token=..." --realm codex-remote
```

## 5. Use It Day To Day

After pairing, Android can:

- Browse projects and thread history.
- Create, rename, archive, unarchive, delete, and clear archived thread history.
- Start new Codex turns from Android.
- Watch Mac-started turns progress on Android.
- Resume threads by selecting them on Android.
- Change per-thread model and settings.
- Receive background notifications for turns and approvals when background relay is enabled.

If Android asks for notification permission, allow it if you want background progress and approval notifications.

## 6. Troubleshooting

Open `Tools` -> `Diagnostics` in the Android app and tap `Copy`. The copied diagnostics summary is redacted and includes app version, pairing status, relay host/path, realm, Mac id, security mode, background relay status, and recent relay/app errors.

Common fixes:

| Symptom | Check |
| --- | --- |
| Android cannot connect | Re-run `/androidex`, confirm the QR shows a `wss://` relay, the tunnel and sidecar LaunchAgents are running, and the Mac has internet access. |
| Quick Tunnel is unavailable | Check `~/Library/Logs/Codex Remote/tunnel.err.log`; if Cloudflare is blocked on the network, use the stable relay option. |
| Stable relay smoke fails | Check DNS, ports `80`/`443`, TLS certificate issuance, and `RELAY_TOKEN`. |
| Pairing screen says release requires secure relay | Regenerate pairing with the default Quick Tunnel or another `wss://` relay URL instead of a LAN `ws://` URL. |
| Background notifications do not appear | Enable Android notifications for Droidex and make sure Background relay is on. |
| Mac does not reconnect after reboot | Check `~/Library/LaunchAgents/com.openai.codexremote.sidecar.plist`, `com.openai.codexremote.relay.plist`, and `com.openai.codexremote.tunnel.plist`, then reload setup. |
| Pairing QR is unavailable | Run `/androidex` again. |
| App shows stale state | Pull down/reopen the app, then select the thread again to force resume/history refresh. |

To rotate pairing credentials:

```text
/androidex --rotate-secret
```

Then scan the new `pairing.png` on Android.

## Safety Notes

- Do not publish a raw `ws://` relay on the internet.
- Do not run a public relay without `RELAY_TOKEN`.
- Do not share `pairing.png`, `pairing.json`, `relay-url`, `sidecar-relay-url`, or `pairing-secret`.
- Use `Tools` -> `Diagnostics` for support instead of sending raw pairing payloads.