First run: chatwire setup¶

After installing chatwire and the launchd agents, the chatwire setup command (or chatwire init) walks you through the first-time configuration and writes ~/.chatwire/config.json.

Before you begin¶

Make sure: - chatwire is installed (chatwire --version works) - The launchd agents are installed (chatwire install-agents was run) - Messages.app is signed in with your Apple ID and has at least one conversation

Run the setup wizard¶

chatwire setup

This prints (and opens) http://127.0.0.1:8723/setup.

The wizard has four steps. A sidebar on the left tracks your progress.

Step 1: Permissions¶

The wizard shows the current status of the two required macOS permissions.

Full Disk Access — the bridge needs to read ~/Library/Messages/chat.db:

Click Open Settings next to Full Disk Access
In System Settings → Privacy & Security → Full Disk Access, unlock the pane and toggle on the Python entry
Return to the wizard — it auto-polls every 30 seconds and will refresh the check

Automation → Messages — required to send messages via AppleScript:

Click Open Settings next to Automation → Messages
Find Python in the list, expand it, and enable Messages
Return to the wizard and click Refresh all if needed

Both rows must show ✓ before the Next → button activates. If you don't see Python in the Automation list, trigger the first prompt: open Script Editor, run tell application "Messages" to get every service, then grant the dialog.

See macOS permissions for the full grant walkthrough.

Step 2: Identity¶

Pick which iMessage handles are yours. The bridge auto-detects handles from chat.db — your phone number(s) and Apple ID email(s).

Check all handles that belong to you. This tells the bridge which messages you sent (outbound) vs. received.

If your handle isn't listed (uncommon on a freshly-signed-in account): - Type it in the Add another handle field: +15551234567 or [email protected] - Include all handles — some people have both a phone number and an email registered

Click Save and continue →.

Step 3: Contact whitelist¶

Pick which contacts' messages should be relayed to the web UI and integrations. Anyone not on the whitelist stays private — their messages remain in Messages.app on this Mac and never reach chatwire.

Add contacts by phone number or Apple ID email. Start with a few trusted contacts to test, then expand later.

You can add, remove, and reorder contacts at any time from Settings → Whitelist in the main UI.

Click Continue →.

Step 4: Security (optional)¶

Protect the web UI behind a password (6+ characters). Without a password, anyone who can reach the URL — on your LAN, via Tailscale, via Cloudflare Access — can read and send messages.

Leave the field blank to skip. Best practice is to gate access at the network layer (LAN-only, Tailscale, Cloudflare Access) rather than relying on a password alone, but the password adds a useful second layer.

The password is stored as a PBKDF2-SHA256 hash in ~/.chatwire/config.json (mode 600). Sessions are signed cookies that expire after 30 days.

Forgot your password? Stop the web agent, open ~/.chatwire/config.json, remove the web.auth block, save, and restart. No reset flow needed.

Click Save and continue → (or Continue → to skip).

Restart the services¶

After the wizard completes, it shows restart commands. Run them in a terminal:

launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge
launchctl kickstart -k gui/$(id -u)/dev.chatwire.web

Then click Open the bridge → or navigate to http://localhost:8723.

Alternative: command-line setup¶

If you prefer to skip the web wizard, chatwire setup also works in CLI-only mode when the web agent isn't running:

chatwire init

This prompts for: - Your phone number(s) or Apple ID email(s) - Whether to install launchd agents now

It writes ~/.chatwire/config.json and optionally calls chatwire install-agents.

What the wizard writes¶

~/.chatwire/config.json (mode 600) with roughly:

{
  "version": 3,
  "self_handles": ["+15551234567"],
  "install_method": "pipx",
  "web": {
    "port": 8723,
    "vapid": {
      "private": "<generated>",
      "public": "<generated>",
      "contact": "mailto:[email protected]"
    }
  }
}

VAPID keys are generated automatically for web push notifications.

Navigate to http://localhost:8723.

If you set a password in Step 4, you'll see a login screen. Enter the password.

Once logged in, the conversation list populates as the bridge syncs recent messages. Initial sync may take 30–60 seconds depending on the size of chat.db.

Run the health check¶

chatwire doctor

All critical checks must show ✓:

Check	What it verifies
macOS	Platform detection
Python	Version ≥ 3.10
Full Disk Access	Can read `chat.db`
Automation → Messages	Can send via AppleScript
config.json	Exists and is mode 600
agent bridge	Plist installed
agent web	Plist installed
loaded bridge	In `launchctl list`
loaded web	In `launchctl list`

A green ✓ on Full Disk Access and Automation → Messages means the bridge can relay messages.

What's next¶

Send a message: click a conversation, type, press Return
Install a plugin: Plugins guide
Set up Telegram relay: Telegram guide
Configure themes: Themes guide
Add the mobile app: Mobile guide
View logs: chatwire logs -f
Monitor health: curl localhost:8723/healthz