Connect Conduck to your AI

Conduck needs an https:// address for anything it reaches beyond your own network. There is one exception, and it covers the common bare setups: a plain http:// address is accepted when only your own network can reach it - a private IP address like 192.168.1.20 or 10.0.0.5, a loopback address, or a name ending in .local. Ollama on :11434, LM Studio, or an Open WebUI box in the next room all connect that way, with no certificate to arrange. Everything else on plain http:// is refused, including a domain name - however private the machine behind it is - and the 100.x addresses an overlay VPN like Tailscale hands out. That is Apple’s rule, decided from the address itself before any request is sent, so Conduck tells you at the moment you type it rather than failing later. Save a plain-http address and the app says so wherever you review that connection: the traffic is not encrypted, anyone else on that network can read your messages and your key, and it only works while you are on that network - not in the car, not out with the Watch. To reach your server from anywhere, put HTTPS in front of it and expose it; conduck-connect walks you through both. One more trap: “localhost” on your phone means the phone itself, and most local servers listen on 127.0.0.1 alone - use the machine’s address on your network instead. For addresses on your home network, iOS also needs Conduck’s Local Network permission (in the iOS Settings app). The full list of what qualifies and what never does: the plain-http rule.

Check the address before anything else. A Cloudflare quick tunnel - the *.trycloudflare.com address you get without a domain - is handed a new hostname every time it restarts, so a setup that worked last night is dead by morning and the setup code you saved points at nothing. Re-run bash conduck-connect.sh --edit on the host: it takes the new address, checks that something answers there, offers to move the file address to the same host, and offers to reprint the setup code - instead of walking the whole wizard again. It recognises a quick tunnel and says so at the top of that screen. For an address that stays put, move to a routed hostname on a named Cloudflare tunnel, to Tailscale Serve, or to your own reverse proxy.

iCloud Private Relay can take over name lookups even while Tailscale reports connected and its own DNS screen says it’s in use - so this one hides well. Your server’s .ts.net name then gets looked up on the public internet, which for a private tailnet-only server returns an address that answers on none of the ports Conduck uses: the server check and the file-server check both fail as unreachable, while the server itself is perfectly healthy. Turn it off in Settings > your name > iCloud > Private Relay, then test again. Private Relay is on by default with iCloud+, so this catches people who did everything right. Quick confirmation: if Safari on the same device can’t load your server’s address either, it’s the lookup - not Conduck.

An HTML page usually means the chat endpoint is still off - it ships off by default on OpenClaw and Hermes. Re-run conduck-connect, or enable it in that gateway’s config and restart. Behind a tunnel or reverse proxy it can also be a login or access page answering instead of your server. A third cause is an address that’s missing a path: some servers host their OpenAI-compatible API below the site root, so the root answers with that server’s own web page - and a 200 makes the address look right. Take the full API base from the project’s own docs and enter it with the path (for example https://host/api, not https://host); Conduck and conduck-connect keep it. If it’s JSON but Conduck still refuses, the shape is wrong: the reply must be an object with a top-level "data" array - see the adapter contract.

Two different faults end in the same refusal, so start with the one that has nothing to do with credentials: the request was rejected as it arrived, before any token was looked at. On a server you set up as keyless there is no token to reject at all, so the usual cause is the address the request was sent to. Ollama works this way - it reads the Host header (the address line every request carries, naming the host it was sent to) and serves only requests addressed to a local name or address, while a tunnel usually forwards your public hostname through unchanged. The tell is that the server answers perfectly on the machine itself and refuses the very same request through your HTTPS address. Fix it at the front: if your tunnel can’t rewrite that line itself, point it at a small local proxy that does - proxy_set_header Host 127.0.0.1:11434; in nginx - rather than at Ollama directly. Ollama skips the check altogether once it listens beyond loopback, so OLLAMA_HOST=0.0.0.0 clears it too, at the cost of answering on every interface. OLLAMA_ORIGINS does not: it allow-lists browser origins for CORS, and Conduck sends none. Then the credential, which is the other fault: if your server does take a token, copy it again from the server and re-pair. If the token is definitely right, check what sits in front - a reverse proxy or access policy (e.g. Cloudflare Access) can reject the request before your server ever sees it. The proxy fix, written out: the Host-header trap.

A self-signed certificate is never trusted, however it’s presented - your device refuses it outright, and nothing in Conduck or conduck-connect can override that. An expired certificate just needs renewing. For a certificate your device already trusts, three routes are free: Tailscale Serve issues one automatically on your private tailnet, nothing exposed publicly; Let’s Encrypt now issues certificates for bare IP addresses too, so no domain is required; or put a domain in front of your server with Caddy or another reverse proxy that mints and renews certificates on its own. Each route is a step-by-step recipe in the certificates and TLS guide, alongside the fix for every certificate error the app can show.

Servers like Ollama, vLLM, and LiteLLM need the model named in every request - set it in that connection’s settings in Conduck (the connection test suggests what your server offers). A 404 when sending usually means that model isn’t available on the server: not pulled or loaded yet, or the name doesn’t match. An empty model list means the endpoint is real but has nothing to answer with - load a model first.

You’re pointed at a chat endpoint, not an agent - and nothing errors, which is what makes this one easy to miss. On Hermes, pair the full-agent API server (port 8642 by default), not the tool-less “hermes proxy” on 8645: both chat, only the API server carries the agent’s tools and skills. And a plain model server - Ollama, LM Studio, vLLM, LiteLLM - only ever chats; Conduck doesn’t execute the tool calls it returns. The chat itself is unaffected either way: Conduck sends this chat’s context with every message, so the thread keeps up wherever you pair it. See what your server can do.

A passing file-server test proves Conduck can store bytes - not that your agent may use them. On OpenClaw, a tools.deny containing group:fs makes every upload invisible to the agent (it web-searches for the filename, or the turn times out into “no response”), reading PDFs natively needs the pdf tool enabled, and saving files back needs write allowed. Separately, a file the agent “sends” as a MEDIA:-style attachment directive is stripped by the chat endpoint - it must name the file in plain reply text instead. On OpenClaw and Hermes, re-run conduck-connect: its file-lane step reads that gateway’s own tool policy, offers the fix where it can safely apply one, and installs agent guidance covering all of this. OpenClaw loads that guidance when a session starts, so test it in a new conversation. On any other OpenAI-compatible server there is nothing agent-side it knows how to configure, so the fix is yours - and it is almost always one of two things. The folder first: the file server has to serve the exact folder your agent reads and writes - an agent in a container, under another account, or on another machine sees a different filesystem than the host you ran setup on, so a path that looks right there can be one it never opens. Then the tools: the agent needs a file-reading tool at all, and its own policy has to allow it. Details: file-lane troubleshooting.

Three different things hide behind this, and only two of them announce themselves. The plain one: the engine behind your server doesn’t read images at all. The honest one: your server declines the picture with a 400 carrying the code image_unsupported, and Conduck tells you the photo was declined and offers to resend the message without it. The bad one: the server answers confidently about a picture it never saw, and nothing in the app can tell. conduck-connect tests for exactly that before you pair - every verification sends one real chat turn carrying a small picture of six random digits and asks for them back. Answer twice, on two different pictures, without coming close, and the run reports photos as unverified rather than broken: from outside, a picture that never reached the engine and an engine that couldn’t read it look identical. It then asks whether to pair anyway, and Enter means no. The fix is one of two things - send pictures to an engine that can see them, or make your server refuse them honestly with that 400 and code. Text-only on purpose? The honest refusal is the supported answer, and it passes the check cleanly.

With your iPhone nearby, the Watch reaches your server through your phone, so a Tailscale-only server works. A standalone Watch - away from your iPhone, on its own Wi-Fi or cellular - can’t reach a Tailscale-only server. For that, expose it with Funnel, Cloudflare Tunnel, or your own HTTPS so the Watch connects directly - what going public costs is set out in the certificates and TLS guide.

402 means your OpenRouter account needs credit; 429 means you’re being rate-limited - wait it out, or add credit to lift the free-tier caps. And conduck-connect refuses to publish a keyless server unless you override it on purpose with --allow-keyless-public, which its refusal message names (adding one by hand, the app warns instead) - keep keyless servers on a private network, or add a token.