CozyLabs
CozyLabs documentation Gateway v0.8.2

Choose your connection.

Connect CozyChat directly to Hermes or OpenClaw, or use CozyGateway for its optional services.

Start with the connection you already run.

On CozyChat’s first screen, choose Hermes Agent, OpenClaw, or CozyGateway. These are connection modes, not three servers you need to install. You can add another later in Settings.

  • Hermes Agent: connect directly to a compatible Hermes API Server with its HTTPS address and API key.
  • OpenClaw: connect directly to a qualified OpenClaw Gateway with its reachable address and credential.
  • CozyGateway: an optional route for push, rooms, routines, device management, and connections across supported computers when your setup supports them.

Choose CozyGateway for its optional services.

This is the installation path for a new CozyGateway. It is useful when its paired services fit your setup. It does not add those services onto an existing direct Hermes or OpenClaw conversation.

  • A Mac, Linux computer, or Windows PC that will stay available to your phone.
  • CozyChat installed on your iPhone. Get the current build from the CozyChat page.
  • An existing Hermes installation, or choose CozyAgents when the installer offers it.

On a trusted home network, answer y to the installer's LAN question. For access away from home, keep the default loopback listener and complete Tailscale setup before creating your pairing code.

The LAN choice binds 0.0.0.0:8787 and uses plain HTTP and WebSocket. Use it only on private home Wi-Fi you control, never guest, public, office, school or shared networks.

Install on your computer.

Run the command for your operating system on the gateway computer. Follow the prompts to connect Hermes or set up CozyAgents and a model.

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

The installer sets up a background service and prints a pairing QR. Reinstalling keeps your saved listener. See what the installer changes for details.

Already have a gateway? Add another CozyAgents computer

Use these only for an additional computer joining an existing gateway:

macOS + Linux 
curl -fsSL https://cozylabs.ai/agents.sh | bash

Windows PowerShell 
irm https://cozylabs.ai/agents.ps1 | iex

Check the gateway. Get a code.

cozygateway status

Look for Status: Ready. Follow any next action the command reports before continuing.

Check that the pairing address is reachable from your phone. A 127.0.0.1 address points back at the device using it, so it cannot connect your phone to the computer. To change the listener: 

cozygateway configure

If you use Tailscale, first save its HTTPS address using the network access guide. Then create a fresh QR: 

cozygateway pair

The setup code has the shape XXXX-XXXX, works once, and expires after ten minutes.

Connect CozyChat.

  1. Open Choose a connection in CozyChat, then choose CozyGateway.
  2. Choose Scan QR code and scan the terminal QR. Or enter the address and setup code, or paste the terminal block.
  3. Open a conversation with a connected bot and send your first message.
What goes in “Gateway address”?

This is your gateway computer's address, not your phone's IP. Scanning the QR supplies the address and setup code automatically. The manual form has these two fields:

  • Gateway address: for example, https://my-computer.tailnet-name.ts.net.
  • Setup code: the current XXXX-XXXX code printed by your gateway.

Use your own setup details, then tap Connect gateway. Pasting the full setup line into either field fills both.

Your phone keeps its device token in the Keychain. The gateway stores only the token's hash. A completed reply confirms the path from your phone through the gateway to the agent.

Make yourself at home

Status checks, adding devices, and maintenance commands.

Connect an existing Hermes API Server directly.

  1. Choose Hermes Agent on CozyChat’s connection screen.
  2. Enter the reachable HTTPS API Server address and its API key.
  3. CozyChat checks the API Server's Sessions, Runs, run event streaming, and durable request-retry support before it saves the connection. A server whose data directory is not writable is rejected.

Direct Hermes keeps chat and history in Hermes. When your server offers them, CozyChat shows tool activity, Stop, one-time and standing approvals, photos, routines, a model choice per conversation, rename, pin, archive, delete, fork, and steering a running turn. The Hermes API Server has no file upload, rooms, push, or voice.

Connect an existing OpenClaw Gateway directly.

  1. Choose OpenClaw on CozyChat’s connection screen.
  2. Enter the reachable Gateway address and the credential its owner provides.
  3. If the owner requires device approval, wait for them to approve the request CozyChat shows, then use Retry.

This path speaks to OpenClaw directly. Do not use cozygateway pair, its QR code, or a CozyGateway setup code here. Direct OpenClaw keeps chat and history in OpenClaw. On a qualified, approved device, it supports text, streaming, tool activity, exact-run Stop for a run this phone started, and one-time exec approvals. It also offers always-allow on exec approvals, rename, pin, archive, and a model choice per conversation.

CozyChat qualified this mode against OpenClaw protocol v4. Files, media, voice, rooms, routines, push, and device-management controls are not part of this direct client path.

Choose a vision model when your paired setup offers one.

A released, compatible CozyGateway and runtime combination can offer a vision-model setting for image analysis when a bot’s primary model cannot see. The control appears only when that connected runtime reports it can configure the setting. Direct Hermes and direct OpenClaw do not show this setting. Hermes offers it only on its Dashboard, which direct mode does not use.

If it does not connect.

The phone cannot reach the address

For CozyGateway LAN access, confirm both devices are on the same trusted home network and its QR uses the computer's LAN address. For a direct Hermes or OpenClaw connection, use the server address that your phone can reach, not the phone's loopback address. For Tailscale, turn its VPN on in the iPhone app and confirm both devices are on the same tailnet. Recheck the access setup.

A CozyGateway setup code expired or was already used

Run cozygateway pair again. Use the new code within ten minutes; each code pairs one device. Direct Hermes and OpenClaw do not use this code.

The app connects, but a bot does not reply

For CozyGateway, run cozygateway status on the computer and follow its reported next action. For a direct connection, check the selected server’s own status, credential, and capability requirements. A reachable server does not by itself prove the agent is ready. If it continues, contact support with status output after removing secrets.

Need a hand? Visit support.

Gateway source · v0.8.2 ↗