caty-gateway

Sound familiar?

If even one of these rings a bell, caty-gateway is for you.

• You asked your AI to do something on your computer, stepped away, and couldn't give it the next instruction
• You had an idea while out and about, and had to explain it to the AI all over again once you got home
• You wanted to show your computer's AI a photo or screenshot from your phone, but had no way to send it
• You signed up for a separate AI app on your phone, but it doesn't share memory with the AI on your computer

The common cause is simple: your computer's AI has no way for your phone to reach it. caty-gateway takes care of exactly that, and nothing more.

Note that caty-gateway is a tool for people already running an AI agent or a local LLM on their computer. It's meant to be used together with the CatyPhone iPhone app. If you don't have an AI running on your computer, or don't use CatyPhone, this isn't for you.

What it does

It connects the AI on your computer and CatyPhone on your iPhone, only inside a private network that belongs to you.

flowchart LR
    phone["CatyPhone<br/>(iPhone)"]
    subgraph tailnet["Your private network (Tailscale)"]
        gw["caty-gateway<br/>(running on your computer)"]
    end
    ai["Your usual AI<br/>Claude Code / Codex CLI / OpenClaw<br/>Hermes / Ollama / LM Studio"]
    phone <-- "voice, photos, screen" --> gw
    gw <-- "via your usual CLI" --> ai

• 🎙️ Talk by voice

  Speak into your iPhone and the AI on your computer answers back. It remembers the earlier part of the conversation. You can optionally set a voice for its replies.

• 📷 Show it photos and your screen

  Send a photo you took, or your shared screen, straight to the AI. You can say "fix this error on my screen" while you're out.

• 🔗 Uses your usual AI as-is

  It doesn't change your AI's settings or working folder. It simply calls the CLI you already use, like Claude Code or Codex CLI, in the background.

• 🔒 Conversations go only to the AI you chose

  Traffic between your iPhone and computer stays inside your private Tailscale network. The gateway itself sends the conversation nowhere, and history is kept on your own computer. If your AI uses the cloud (Claude Code, Codex CLI and the like), that is the same traffic that AI always has.

On the computer side you only need three things.

What you need

You need "an AI", "Tailscale", and "ffmpeg" on your computer, plus CatyPhone on your iPhone.

Supported AIs (backends)

A "backend" is the AI that caty-gateway talks to behind the scenes. You choose it with the --backend value.

• Bundled — this repository ships an adapter and tests for it
• Connectable — connects through the openai-compat OpenAI-compatible API
• Planned — no adapter yet. See Contributing for how to add one

"Live-conversation record" means whether this repository has a written walkthrough of an actual back-and-forth conversation from an iPhone. Until that record exists, this column stays "In progress".

Three things your computer needs

Tailscale is a free app that creates a private network connecting only your own devices to each other. caty-gateway assumes your iPhone and computer are on the same Tailscale network, and pairing (scanning the QR) is not accepted from any other route. After pairing, every request is protected by the key (token) handed over at that moment.

Once you have these, you can get started with a single command.

Getting started

There are four steps: install → check → set up → scan the QR code.

Have your AI install it for you

You can paste the following three lines to your AI agent and ask it to do this for you.

Please read https://github.com/caty-ai/caty-gateway and install caty-gateway.
To install it, run `uv tool install caty-gateway` (or `pipx install caty-gateway` if you don't have uv; if you have neither, follow the steps in the README).
Once installed, run `caty-gateway doctor --backend claude` and show me the result as-is.

The commands are spelled out on purpose, so the agent doesn't have to guess how to install it. Only the official package gets installed, and doctor only checks things — it never changes anything.

Install it yourself

1. Install

The one-command installer sets up uv if it's missing, then installs caty-gateway. It is coming with the PyPI release; until then, use the uv command below it.

curl -fsSL https://caty.talk/gateway/install.sh | sh

If you already have uv:

uv tool install caty-gateway

If you don't have uv, pipx install caty-gateway works the same way.

2. Check

caty-gateway doctor --backend claude

Replace claude with the --backend value from the table above. When only PASS and WARN remain, you're ready to go. Any FAIL line comes with instructions for fixing it. WARN marks a check that could not be confirmed passively; if that AI works as usual, carry on.

PASS OS
PASS Python
PASS ffmpeg
PASS ffprobe
PASS tailscale executable
PASS tailscale login
PASS tailscale IPv4
PASS port
PASS public URL
PASS config directory
PASS state directory
PASS data directory
PASS claude version
PASS claude working directory
PASS claude credentials

3. Set up

caty-gateway setup --member me --backend claude

Replace me with a short name for yourself using letters and numbers (or just keep me). This creates a background service that starts every time your computer boots, and shows a QR code at the end. If you just want to preview what it will do first, add --plan-only to see the full plan without changing anything.

Running it over ssh or from a script? Add --yes (there is no terminal to answer the confirmation) and put CATY_QR_DELIVERY=tty in front so the QR code is drawn as text: CATY_QR_DELIVERY=tty caty-gateway setup --member me --backend claude --yes

4. Scan the QR code

Open CatyPhone and scan the QR code shown on screen. Your iPhone and computer will connect, and you'll be able to start talking. The QR code expires after 10 minutes, and can only be scanned once. To get a new one, run caty-gateway qr --member <id> (see Reissuing the QR).

Now that it's connected, here's what this tool deliberately does not do.

Why it is safe to install

caty-gateway only handles the "front door" — it doesn't do anything extra to your AI or your conversations.

• It doesn't change your AI's settings

  it talks to Claude Code and others by calling the same CLI you already use. It never touches your working folder or config files

• Checks only look, they don't act

  doctor only checks version numbers and login status; it never sends a prompt to your AI (so it never uses up any of your usage quota)

• Pairing only happens inside your private network

  pairing requests are only accepted from inside your Tailscale network, or from the computer itself. After pairing, every request without the key (token) is refused

• The QR code never carries a long-lived key

  it only contains a one-time password that expires in 10 minutes; the real key is handed over separately, after scanning

• Records stay on your computer

  conversation history is stored at ~/.local/state/caty-gateway/history/<name>/, and deleting that folder deletes it

The gateway sends the conversation only to the AI you chose. Beyond that, nothing goes out except for optional features you turn on yourself, such as text-to-speech or avatar generation. Which features send what is documented in privacy.

If something still isn't working, look for it in the list below.

When something goes wrong

First run caty-gateway doctor --backend <value> and follow the instructions next to any FAIL line. If you're still stuck, look for your symptom below.

You can find the full picture of how it works and how to configure it in the documents below.

Learn more

Documentation is split by what you're looking for. The engineering guide and the reference have Japanese versions, linked at the top of those two pages.

Adding or fixing a backend is welcome — here's how.

Contributing

Adding support for the AI you use can be as simple as writing one preset.

Setup steps, test conventions, and the review process are in CONTRIBUTING.md. For bugs or questions, please open an issue.

Part of the Caty AI family — open tools for running a family of AI agents. The full map, including modules still being prepared for release, lives in Family OS.

License

MIT License. We chose a license that lets anyone freely use and build with this, so you can add a front door to your own AI too.