help

Setup fast.
Repair fast.

These are the canonical DexRelay Mac commands for install, pairing, repair, and uninstall. If something breaks, start with dexrelay status, then dexrelay repair.

Last updated: April 10, 2026

1. Install on Mac

Recommended clean-Mac install flow:

curl -fsSL https://assets.dexrelay.app/install.sh | bash

npm install flow when npm is already installed and writable:

npm i -g dexrelay

The install flow sets up the DexRelay runtime on your Mac, installs the local bridge and helper, and starts the required launch agents.

2. Pair Your iPhone

After install, run this on your Mac and scan the QR in the iPhone app:

dexrelay pair

3. Use DexRelay Outside Wi-Fi

Use Tailscale so DexRelay still works when you are away from your home or office Wi-Fi and want to ship without being near your Mac.

  1. Download Tailscale on your Mac and your iPhone.
  2. Log in with the same Tailscale account on both devices.
  3. DexRelay will automatically find your Tailscale and use it for remote access.
Download Tailscale for Mac Download Tailscale for iPhone

4. Health and Repair

Use these commands in this order when DexRelay is unhealthy:

  1. Check status.
  2. Confirm Tailscale is actually available on the Mac if you expect remote access.
  3. Run repair.
  4. Rerun install only if repair is insufficient.
dexrelay status dexrelay repair dexrelay install

5. Project Setup and Buttons

Every project in DexRelay has a Project Setup. It keeps your backend services predictable and defines the buttons you see in the play menu.

Under the hood DexRelay stores two files in the repo:

  • .dexrelay/project-governance.json for services, ports, health checks, and backend setup.
  • .dexrelay/project-runbook.json for the project buttons shown in the app.

For normal use, think about it like this:

  1. Open a project.
  2. If you see Generate Setup or Repair Setup, tap that first.
  3. Use Start Services to bring up the project backend.
  4. Use the play menu buttons for your app workflow.
  5. Use Add Project Button to describe a new workflow in plain English.
  6. Use Remove Project Button when a button is obsolete.

Examples of buttons you can add:

  • Run Backend to start a Python API and show its health URL.
  • Open Admin to launch a local or Tailscale-served admin page.
  • Seed Demo Data to run a setup script before testing on iPhone.
  • Reset Dev DB to clear and rebuild a local database safely.
  • Run Simulator Smoke to boot a simulator and run a standard smoke test.

The goal is simple: each project should know which services it owns, which ports it uses, and which buttons make sense for that app.

6. Uninstall

To remove DexRelay from your Mac:

dexrelay uninstall

This removes the DexRelay runtime, launch agents, logs, and the Homebrew CLI if it was installed through Homebrew.

7. Keep-Awake Controls

DexRelay also exposes keep-awake controls for the Mac runtime:

dexrelay wake on dexrelay wake off dexrelay wake status

8. Advanced

Advanced or internal relay bootstrap flow:

dexrelay relay-pair

If you need support or want website signup information deleted, contact [email protected].