Setup guide

Three ways to connect.

Kuya talks to Hermes Agent. Pick the path that matches where your Hermes is, or where it will be. Each one ends the same way: Kuya on your iPhone, paired and ready.

Before you start

  • An iPhone on iOS 27 or later, with Kuya installed.
  • For the computer paths, the iPhone and the computer on the same Wi-Fi. To use Kuya away from home too, install Tailscale on both and sign in to the same account.

Watch setup in 60 seconds

Video coming soon

Path 1 · 1 step

I have a code

Someone set up Hermes for you and sent a link or QR code, or you got a Kuya Cloud invite by email.

  1. Tap the link on your iPhone, or scan its QR code.

    A Kuya Cloud invite arrives as an email from Brandon. Open it on your iPhone and tap Connect. If the link came in a text message, tapping it is enough. Reading the email on a computer? Point your iPhone's camera at the QR code in it.

    You can also start from the app: open Kuya, tap I have a code, then Scan QR code, or paste the link. Kuya accepts the whole message the link came in.

That's it. Kuya opens already paired. A brand new Kuya Cloud agent takes about 30 seconds to build the first time you tap Connect.

Good to know

  • A Kuya Cloud invite link works once. If it has been used or has expired, ask for a new one.
  • Got a new phone? Ask for a new invite. Connecting the new phone signs the old one out.

Path 2 · 3 steps

Set up on my computer

Nothing installed yet? Kuya Pair is a free app for Mac, Windows, and Linux. It installs Hermes if you don't have it, signs you in to an AI service, and shows a code for your iPhone to scan.

Get Kuya Pair

Mac, coming soon Windows, coming soon Linux, coming soon

Kuya Pair download coming soon

  1. Get Kuya Pair on your computer.

    In Kuya on your iPhone, tap Set up on my computer. The screen has a button to send the download link to yourself, so you can open it on the computer.

  2. Open it and follow its steps.

    Kuya Pair has four steps. Each one says what it will do and asks before it does anything.

    • Get Hermes. Runs the official Hermes installer. A Hermes you already have is left alone.
    • Sign in to your AI. ChatGPT signs in with a short code in your browser. For OpenRouter or Anthropic, paste a key and Kuya Pair checks it with the provider.
    • Keep it running. Sets Hermes to start again after the computer restarts. On a Mac it can also keep the computer awake, if you want that.
    • Pair your iPhone. Shows a QR code.

  3. Scan the code with Kuya.

    Back on your iPhone, tap Scan the code on your computer and point the camera at the screen. You're connected.

Good to know

  • The QR code holds your access key, so the window keeps it hidden until you click Show.
  • A code works for 10 minutes. Kuya Pair makes a fresh one on its own before that.
  • Nothing is sent anywhere. Your phone reads the code straight from the screen.
  • Hermes runs on your computer, so the computer needs to be on when you want to use it.

Path 3 · 2 steps

I already have Hermes

Hermes Agent 0.21 or later already runs on your Mac, a Linux box, a Windows PC, a home server, or a VPS.

  1. Run hermes-pair on the machine that runs Hermes.

    It's a small, free tool. Install it and run it in one go:

    On the Hermes machine
    pipx install "git+https://github.com/mortykaidev/kuya-setup#subdirectory=hermes-pair"
hermes-pair

    It turns on the Hermes API server if it's off, creates an access key if there isn't one, picks the address your phone can reach (Tailscale first, then your home network), and prints a QR code. It never overwrites a key or setting you already have, and it sends nothing anywhere.

    No pipx? Use pip install --user with the same address, or see the kuya-setup repo for other ways. If the tool changed anything, run hermes-pair --restart so the gateway picks it up.

  2. Scan the code with Kuya.

    In Kuya, tap I already have Hermes and scan the QR code. Done.

Rather type it in?

The same screen takes the address and key by hand. On the Hermes machine, make sure ~/.hermes/.env has these lines, then restart the gateway:

~/.hermes/.env
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_KEY=<a long random string>
  • Address: http://<tailscale-or-lan-ip>:8642
  • Key: the value of API_SERVER_KEY

Server settings, tools, and skills

Those screens use the Hermes dashboard (port 9119) and need its login. In Kuya, open Settings, pick the connection, and tap Add dashboard login. Chat works without this step. Kuya Pair can also set up the dashboard login for you.

New to Hermes?

Hermes Agent is open source and lives at github.com/NousResearch/hermes-agent. If you'd rather not install it by hand, use Kuya Pair.

Want to look around first?

Kuya's welcome screen has Try a sample chat. It shows the interface with sample conversations. It's a tour, not a working agent.

Stuck? Get help