Make yourself at home. · CozyLabs docs

A guide for where you are.

CozyChat starts with a connection choice. Use an existing Hermes API Server or OpenClaw Gateway directly, or choose CozyGateway for its optional paired services. Start with the connection guide if this is your first setup.

Choose a connection

Direct Hermes, direct OpenClaw, or CozyGateway from first screen to first message.

Reach your agents away from home

Private HTTPS with Tailscale, trusted home Wi-Fi, or an advanced tunnel.

Run Docker + Hermes

Choose one private Docker network or keep Hermes on another host.

Install the gateway.

Run this on the computer that will host CozyGateway. It is an optional connection route that can connect an existing Hermes installation or offer CozyAgents and a model. The default command installs the newest release.

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

What the installer changes

what the installer does
step	what happens
verifies	every download against the release checksums (SHA-256)
adds	Node 24, only if missing
asks, no Hermes	which harness runs your bots: CozyAgents (Enter) or Hermes Agent, then which provider or local endpoint and which model new bots use
keeps	an existing Hermes Agent, and opens its model picker
asks	Allow CozyChat to access this Gateway over your local network? [y/N]; Enter keeps `127.0.0.1:8787`
ends with	a pairing QR and plain-text code in the same terminal
runs as	macOS launchd, Linux `systemd --user` (needs a login session and `loginctl`), Windows current-user Scheduled Task, no admin
again	re-run to update in place; uninstall supported; containers use the Docker guide

Add CozyAgents on another computer

For an additional computer joining a gateway you already run. The gateway installer offers CozyAgents during first setup, so you do not need a separate installation for that path.

macOS + Linux

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

Windows PowerShell

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

Choose network access.

By default, fresh installs listen on 127.0.0.1:8787. That address belongs to the computer itself; your phone needs a reachable LAN or HTTPS address before it can connect. The installer asks:

Allow CozyChat to access this Gateway over your local network? [y/N]

the local-network question
answer	result	use when
y	listens on `0.0.0.0:8787`; the QR carries a LAN address	private home Wi-Fi you control; never guest, public, office, school or shared; never forwarded on the router
Enter, n, no terminal attached	stays on `127.0.0.1:8787`	anywhere else; add Tailscale Serve for remote access and keep loopback

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

A reinstall keeps your saved listener. To change it later:

cozygateway configure

For remote use, follow the Tailscale setup before pairing.

Check it. Keep it running.

Run this on the gateway computer on macOS, Linux, or Windows:

cozygateway status

Look for Status: Ready. If the check reports a problem, follow its next action. A running service alone does not confirm that a bot can complete a turn; send a message after setup.

Repair or update an existing installation

The repair command reruns the installer. Review the status output first so you know what needs attention.

cozygateway repair

Docker installations use the Docker update procedure.

Pair another device.

Create a fresh QR code on the gateway computer. It works once and expires after ten minutes.

cozygateway pair

In CozyChat, choose CozyGateway, then choose Scan QR code. You can also enter the address and setup code, or paste the terminal block. This QR belongs only to the CozyGateway path. See the connection guide for every route.

Uninstall when you need to.

Remove the macOS or Linux installation

This removes the service and plugin. Your SQLite data remains until you delete it. The command below is for macOS and Linux installations in the default directory.

bash ~/.cozygateway/bin/agent-install.sh --uninstall --gateway-dir ~/.cozygateway

For another installation type, use support to identify the correct service and data paths.

Need a hand? Visit support.

Gateway source · v0.8.2 ↗