CozyLabs

// cozychat support

Set up CozyChat and fix connection problems

Start with pairing. For a failure, find the symptom and follow its checks.

CozyChat for iPhone ยท Version 1.0

Getting started

  1. On the gateway host, use the command for macOS, Linux, or Windows.

    macOS + Linux

    terminal 
    curl -fsSL https://cozylabs.ai/setup | bash

    pin a specific release

    Installs v0.8.2 instead of the newest release, for reproducing a bug report.

    terminal 
    curl -fsSL https://cozylabs.ai/setup | COZYGATEWAY_INSTALL_TAG=v0.8.2 bash

    Windows PowerShell

    powershell 
    irm https://cozylabs.ai/setup | iex

    pin a specific release

    Installs v0.8.2 instead of the newest release, for reproducing a bug report.

    powershell 
    $env:COZYGATEWAY_INSTALL_TAG='v0.8.2'; irm https://cozylabs.ai/setup | iex

    No Hermes on this computer? The installer offers CozyAgents.

    Add another computer to an existing gateway:

    macOS + Linux

    terminal 
    curl -fsSL https://cozylabs.ai/agents.sh | bash

    Windows PowerShell

    powershell 
    irm https://cozylabs.ai/agents.ps1 | iex

  2. answerresultuse when
    ylistens on 0.0.0.0:8787; the QR carries a LAN addressprivate home Wi-Fi you control; never guest, public, office, school or shared; never forwarded on the router
    Enter, n, no terminal attachedstays on 127.0.0.1:8787anywhere else; add Tailscale Serve for remote access and keep loopback

    Reinstalls keep your answer. Change it later: cozygateway configure.

  3. The installer ends with a pairing QR and plain-text code in that same terminal. Run cozygateway pair for a fresh one, or cozygateway pair --url <origin> for an HTTPS route.
  4. In CozyChat, choose Pair a gateway.
  5. Scan the pairing QR code, or choose Type code and enter the gateway address and setup code.
  6. Open a bot and send a message. Its reply streams into the conversation.
what the installer does
stepwhat happens
verifiesevery download against the release checksums (SHA-256)
addsNode 24, only if missing
asks, no Hermeswhich harness runs your bots: CozyAgents (Enter) or Hermes Agent, then which provider or local endpoint and which model new bots use
keepsan existing Hermes Agent, and opens its model picker
asksAllow CozyChat to access this Gateway over your local network? [y/N]; Enter keeps 127.0.0.1:8787
ends witha pairing QR and plain-text code in the same terminal
runs asmacOS launchd, Linux systemd --user (needs a login session and loginctl), Windows current-user Scheduled Task, no admin
againre-run to update in place; uninstall supported; containers and WSL without systemd use the Docker guide

The welcome tour runs before pairing; reopen it from Settings. Bots load only from a running CozyGateway.

Connecting away from home

You configure the route, then pair CozyChat with the address your iPhone uses.

  • Tailscale Serve, recommended: install it on the gateway host and iPhone, join one tailnet, and run Serve, not Funnel, for tailnet-only HTTPS. If anyone on the tailnet is untrusted, restrict gateway access on TCP 443.
  • Cloudflare named tunnel, advanced and public: it is reachable from the Internet with no router port open. CozyChat sends no Access headers, so Access cannot gate it. Keep CozyGateway on loopback and pass WebSocket, Authorization and Range through.

Never forward port 8787 on your router.

The project's connectivity guide includes each command and verification check.

Photos

Choose a photo or take one with the camera. CozyChat prepares it on your iPhone before sending it to your gateway.

Notifications

Enable notifications during setup or in iOS Settings. Your gateway encrypts each preview before the CozyLabs relay forwards it to Apple without a key.

Troubleshooting

Pairing fails

  • Run cozygateway status. Same-Wi-Fi pairing needs 0.0.0.0:8787.
  • Create a fresh setup code. It expires after 10 minutes and works once.
  • Use http:// only on a trusted home LAN. Remote routes require https://.
  • For a local gateway, use the same network. For Tailscale, confirm both devices are online. For a tunnel, open the public hostname before pairing.
  • For a changed self-signed gateway identity, ask the operator to verify it before accepting.

Messages do not arrive

  • Check that the gateway and its harness, CozyAgents or Hermes, show online.
  • Open the bot after the gateway reports that it is ready.
  • If CozyChat marks a message as failed, choose Retry.

Notifications do not arrive

  • Allow CozyChat notifications in iOS Settings.
  • Check that the gateway can reach its relay.
  • Background the app, then send a completed reply. Streaming fragments do not each notify.

Forget a gateway

Settings > gateway > Forget gateway deletes the local credential, trust record and notification key and asks the gateway to revoke the device. Forgetting the last gateway also unregisters push. Removal completes even if either service is offline.

Contact

Email [email protected] with CozyChat and iOS versions and what happened.

Do not email a gateway bearer token, setup code, notification key, private chat text, or photo. Hide private addresses and content in screenshots.

For data-handling details, read the CozyChat privacy policy. Gateway setup and source code are available from the cozygateway project.