Your agents, within reach.

Pick one path.

CozyGateway starts on loopback, 127.0.0.1:8787. Your phone needs a route to that computer. The installer never changes Tailscale, DNS, tunnels or firewall policy.

Tailscale Serve

Private HTTPS on your tailnet. The secure remote default.

Same home Wi-Fi

Direct access on a private home network you control. Trusted LAN only.

Cloudflare named tunnel

A public HTTPS hostname. For operators comfortable managing Internet exposure.

Tailscale Serve.

Keep CozyGateway on loopback. Tailscale connects your devices privately; Serve adds HTTPS without opening a router port. Install Tailscale on the gateway computer and your iPhone, then sign in to the same tailnet.

1. Connect both devices

On the computer, connect Tailscale and check its status. On the iPhone, turn the Tailscale VPN on.

tailscale up
tailscale status

2. Enable private HTTPS

Use Serve, not Funnel: Funnel publishes the service to the Internet.

tailscale serve --bg --https=443 http://127.0.0.1:8787

tailscale serve status

3. Save the address and pair

Running Docker? Use the Serve origin with pair --url in the Docker pairing command. The installer commands below are for native installations.

Copy the HTTPS origin shown by Serve. On macOS or Linux, replace the example hostname below with that exact origin. This saves it in CozyGateway so future pairing slips advertise the same address.

macOS + Linux

curl -fsSL https://cozylabs.ai/setup | bash -s -- --public-url https://my-hermes.tailnet-name.ts.net

On Windows PowerShell, save the same origin with:

Windows PowerShell

& ([scriptblock]::Create((irm https://cozylabs.ai/install.ps1))) -InstallerArguments @('--public-url', 'https://my-hermes.tailnet-name.ts.net')

cozygateway pair

Return to Connect CozyChat and scan the new QR.

New tailnets allow all devices to reach one another by default. On a shared tailnet, restrict this gateway to the intended user or device on TCP 443. Read Tailscale's grants reference before changing shared policy.

Trusted home Wi-Fi.

For trusted LAN only: choose 0.0.0.0, port 8787, and put your phone on the same private home network. The installer offers this when you answer y to its LAN question. To change an existing installation:

cozygateway configure

cozygateway pair

The QR must use the computer's LAN address, not 127.0.0.1 or 0.0.0.0.

LAN traffic uses plain HTTP and WebSocket. Never use this on guest, public, office, school or shared networks, or with router port forwarding. Use Tailscale if you are unsure.

Cloudflare named tunnel.

advanced · Internet-facing

A published tunnel creates a public HTTPS hostname. It avoids an inbound router port, but anyone on the Internet can reach that hostname. Keep CozyGateway on loopback and use a domain you control.

Cloudflare Access is not a drop-in option for CozyChat today. The app cannot complete an interactive Access or Basic Auth login; use Tailscale Serve when you need an identity-gated private route.

Configure a durable named tunnel

1. Create the tunnel and DNS route

cloudflared tunnel login
cloudflared tunnel create cozygateway
cloudflared tunnel route dns cozygateway gateway.example.com

2. Save the public gateway origin

Replace the example hostname with your own. This macOS/Linux command configures the public origin while keeping the gateway listener on loopback.

macOS + Linux

curl -fsSL https://cozylabs.ai/setup | bash -s -- --public-url https://gateway.example.com

Windows PowerShell

& ([scriptblock]::Create((irm https://cozylabs.ai/install.ps1))) -InstallerArguments @('--public-url', 'https://gateway.example.com')

3. Configure ingress

Use the tunnel UUID and private credentials-file path created above. Keep the final catch-all rule.

config.yml yaml

tunnel: <tunnel-uuid>
credentials-file: /path/you/control/<tunnel-uuid>.json
ingress:
  - hostname: gateway.example.com
    service: http://127.0.0.1:8787
  - service: http_status:404

Run cloudflared tunnel run cozygateway, or use Cloudflare's service installation instructions for your operating system.

4. Pair and verify

cozygateway pair

Scan the QR in CozyChat and send a message. The tunnel must forward the /ws upgrade plus Authorization and Range headers.

Use a named tunnel. Quick-tunnel hostnames rotate and break pairing.
Protect tunnel credentials and rate-limit /pair at the edge.
Never put a device token or setup code in a URL.
/attach/v1 is the separately authenticated harness channel, not the phone connection.

The tunnel is transport only; the device token is application authentication. A setup code exchanges for a random 256-bit device token. CozyChat keeps it in the Keychain, the gateway stores its hash, and it travels as Authorization: Bearer on REST and in the first message on /ws.

Ports and certificate trust.

do not forward port 8787 through your router. That exposes the service without TLS. A public reverse proxy needs HTTPS on 443, a private gateway listener, WebSocket and Authorization forwarding, and no bearer tokens in URLs.

CozyChat uses normal iOS trust for CA-issued HTTPS. Trust-on-first-use pinning applies only to self-signed certificates, and a changed leaf certificate fails closed.

References: Tailscale Serve, Funnel, default tailnet policy, Cloudflare published applications, and Apple transport security.

Need a hand? Visit support.

Gateway source · v0.8.2 ↗