Debug the connection from the server outward.

1. Confirm versions and server mode

Update KKCode to the latest release and use a current OpenCode release. Start opencode serve for a dedicated API.

opencode --version

2. Test the exact API base

Append /global/health to the same base URL entered in KKCode:

curl -i -u your-user:your-password \
  https://your-opencode-host.example/global/health

Expected: a successful HTTP response containing OpenCode health data.

• HTML response — you probably entered the web UI rather than the API base.
• 404 — check whether the API is mounted below /api or another prefix.
• 401/403 — verify OPENCODE_SERVER_USERNAME and OPENCODE_SERVER_PASSWORD.
• Timeout / DNS failure — fix the network, tunnel, VPN, or hostname before changing the app.

3. Check the selected transport

For Tailscale, confirm both devices are connected to the same tailnet, ACLs allow the route, and tailscale serve status points at the OpenCode port.

For Cloudflare Tunnel, confirm cloudflared is running, the hostname resolves, ingress targets 127.0.0.1:4096, and authentication remains enabled.

For the built-in QR tunnel, restart npx -y @kkcode-app/agent@latest on the dev machine and rescan the QR in KKCode. If the relay is unreachable, fall back to LAN, Tailscale, or Cloudflare.

For a reverse proxy, preserve the API prefix, authorization header, and the SSE stream.

4. Interpret the app state

• Connected but no workspaces — confirm OpenCode version compatibility and that a project directory is reachable from the dev machine.
• Messages update only after refresh — inspect the SSE / realtime status and proxy support for the event stream.
• Authentication fails — match the username and password to the server environment variables. Editing the connection fields does not start a new connection automatically; tap Reconnect.
• Tunnel works in the browser but not in the app — use the actual API base path; do not paste a URL that returns HTML.

5. Collect a useful bug report

Include the KKCode release, OpenCode version, connection method, sanitized API base shape (no credentials), the health-response status, and the visible error. Never include passwords, provider keys, private hostnames, customer data, or source code.

Search the GitHub issue tracker before opening a duplicate. Security-sensitive reports go to the email in the footer of kkcode.app, not to public issues.