yeti
Docs: Skills & tools

Skills & tools

Connect Gmail and Google Calendar with your own Google OAuth client. Tokens stay sealed on your cubes.

Tools are your own accounts that your yeti can use. Skills are the things your yeti do with them. Today the tools are Gmail and Google Calendar; skills built on them are marked Soon in the app.

Your cubes talk to Google directly. Nothing goes through a yeti server, and yeti doesn't ship a shared Google key: you make your own OAuth client, so only you can use it.

Set up Google (once)

Open Skills & tools and choose Set up Google. The guide has a button for each Google page.

  1. Create a Google Cloud project. Any name works; try yeti.
  2. Turn on the Gmail and Calendar APIs. With your project selected, open each and choose Enable. Skip the one you won't use.
  3. Set up the consent screen. In Google Auth Platform choose Get started: app name yeti, your email as support contact, audience External. Then open Audience and add your own Google address under Test users. You don't need to add scopes; yeti asks for them when you connect.
  4. Create a Desktop app client. Under Clients, choose Create client, application type Desktop app, name yeti desktop. Copy the client ID and client secret, or download the JSON.
  5. Paste them into yeti (the JSON can go in the first field) and choose Seal on my cubes.

The client secret goes straight to your cubes and is sealed with your cluster's key. The app can't read it back. To swap clients later, choose Replace.

While your Google app's publishing status is Testing, Google ends the sign-in after 7 days and you reconnect. To avoid that, set it to In production on the Audience page. Google then shows an "unverified app" screen for your own app, which you can continue past.

Connect an account

Choose Connect Google. For each service, switch it on and pick how much your yeti may do:

Service Read Write
Gmail Read and search your mail. Can't label, send or delete anything (gmail.readonly) Read, label, archive, draft and send mail. Can't delete mail for good (gmail.modify)
Google Calendar See your calendars and events. Can't change anything (calendar.readonly) See, add, change and delete events. Can't share or delete calendars (calendar.events)

yeti also asks for your email address, only to show which account is connected. If you untick anything on Google's screen, yeti uses only what you allowed.

Then choose Sign in with Google:

  1. Your browser opens Google's sign-in. Allow access there.
  2. Google hands a one-time code back to this computer only, on 127.0.0.1. yeti uses PKCE and a one-time state check, and the listener accepts exactly one answer. You have 5 minutes.
  3. A cube trades the code for a token, checks Gmail and Calendar once, and seals the token. If that check fails, the new grant is revoked so nothing is left behind.

You can connect more than one Google account.

Manage a connection

Each connected account shows what it can do, when it was connected and last checked, its message and calendar counts, its scopes, and the name its token is sealed under (google/<account>/token).

  • Test has a cube refresh the token if needed and call each service once.
  • Change access signs in again with different choices.
  • Disconnect asks Google to revoke access, then deletes the sealed token from your cubes. If Google can't confirm the revoke, yeti still deletes its copy and tells you to remove yeti at myaccount.google.com/permissions too.
  • Reconnect appears when a check fails.

How your yeti use tools

Your yeti use a connected account only with the access you granted: a yeti on a read-only Gmail connection can search and read mail but can't send. The cubes do the work: they search Gmail (gmail.search) and list calendar events (calendar.events) with the sealed token, which never leaves them. Anything on a yeti's "Always check with me before…" list still waits for your ok, so a yeti with write access asks before sending a message if Sending messages is on its list.

Where things live

What Where
Your OAuth client (ID and secret) Sealed cluster secret google/oauth-client. The client ID is also kept unsealed, since it appears in every sign-in link
Each account's token Sealed cluster secret google/<account>/token, written by a cube. The desktop app never holds a token
The one-time sign-in code A sealed secret under google/pending/ for the few seconds a cube needs it, then deleted
Account, access, counts, last check An unencrypted record in your cluster's store. Nothing in it is secret

Security explains sealing and its limits.