Connect your apps

Give Oktapod access to email, calendars, contacts, documents, tasks, search, and more, and keep those connections healthy.

A connection lets Oktapod read from or act in one of your apps. Connect only what you need; you can add more at any time.

A connection gives Oktapod the ability to act, not permission. Reading your calendar can happen on its own; sending an email, creating an event, or changing a task still asks you first. See Approvals and safety.

#Connect an app

The quickest way is to ask:

Connect my Google calendar.

Oktapod replies with a connection card that opens the right setup form on the Connections page. This works for every app in the table below. Apps that need no sign-in, such as Kiwi flights, Open-Meteo weather, and Mac Contacts when Oktapod runs on a Mac, get a reply saying they are already available. You can also type /apps to browse all cards, or /connect <app>, for example /connect todoist.

Google and Microsoft accounts need the one-time sign-in setup described in Google and Microsoft sign-in. Until it is done, asking to connect one of them points you to that step.

You don't have to connect anything ahead of time. Ask for what you need, for example:

Add "call the dentist" to my Todoist.

If that app isn't connected yet, Oktapod offers its card instead of an answer. Once you finish signing in or saving the form, it picks up the same request on its own and replies in that conversation. This works when the setup is finished within 30 minutes of the request, and only for requests typed in the app or web chat. Connecting an app never approves anything by itself: a send or change it then makes still asks you first.

On the Connections page, find the app, choose Sign in or fill in its details, and follow the steps. When a sign-in finishes, Oktapod reports the result in the conversation that asked for it.

On iPhone and Android the same card appears in the chat. Its button opens the provider's sign-in page or the private setup form in your browser, at your agent's address.

Setup forms are private. Keys and passwords go straight into Oktapod's local credential store; never paste them into a chat message.

#What you can connect

Notion pages and Obsidian notes can be written as well as read, and Todoist and Microsoft To Do can add and complete tasks. CalDAV Tasks, ICS feeds, and FreshRSS are read-only. Writing to a note or page asks for your approval first; a task you ask for directly in chat is added straight away.

The page groups these as Communication, Knowledge & work, Search, Creative media, Automation, and On this device.

AI models are not connections. They are set up under Models; see Models and routing. Messaging apps have their own page; see Messaging channels.

#Flights and shopping

#Direct store checkout

Open Connections → Shopify store and enter the store's public canonical address, such as https://store-name.myshopify.com. Supported tokenless Storefront APIs need no Shopify account or API key. The form rejects unrelated domains and invalid store addresses.

Oktapod reads products, exact variants, current prices, currency, and availability directly from the store. Choose the right size, colour, and quantity. It checks those variants again before preparing a cart through the merchant API and returning the merchant's payment link. Cart creation follows the external-write approval rules. Replayed requests reuse their saved result; uncertain attempts are not automatically submitted again.

An optional country code requests the relevant market's prices. A budget must include its currency. Stock, variant, quantity, currency, or price changes stop checkout preparation for a fresh review. The quoted items subtotal excludes shipping and taxes; the merchant checks the final total. You enter delivery and payment details in that merchant checkout. Preparing the cart submits no order or payment.

#Kiwi flight search and booking links

Kiwi flights is ready without a key or sign-in. Ask for flight options with your locations, dates, passenger counts, and baggage needs. Oktapod uses Kiwi's official MCP to return price snapshots, airport-local dates, carriers, baggage totals across all passengers, and booking links. You review and pay on Kiwi. Finding an option does not reserve a seat or complete a purchase.

Separate-ticket self-transfers, overnight layovers, and airport changes are excluded by default. Enable them explicitly when wanted, and review transfer protection and fare conditions at checkout. Prices and availability can change; Kiwi confirms the final total. A provider outage reports an error rather than silently replacing live flight data with web research.

/travel.kiwi.search {"origin":"BEG","destination":"LHR","departure_date":"2026-10-29","adults":1,"currency":"EUR","max_stops":0}

Use future ISO dates. Optional return_date makes a return trip; maximum_price limits the total for all passengers in the selected currency. Kiwi is the initial travel connector; Duffel is optional.

#Optional Duffel booking

Open Connections → Duffel travel and save a Duffel token in the private form. Set the HTTPS address to return to after the provider's checkout. Start with a Duffel test token; test fares are synthetic. Production calls use your account's access, fees, and eligibility.

Oktapod searches airline offers and refreshes exact offer IDs, including price, currency, itinerary, baggage, and expiry. Duffel-hosted booking links support flights and accommodation. Their search-and-book checkout lets you choose your trip and pay with Duffel. These links are not bound to a previously quoted offer, expire within 24 hours, and are single-use. Link creation does not mean a booking or payment completed. A successful return redirect is not payment evidence.

Hosted links require an eligible Duffel organisation in a supported Payments country. API fixtures cannot prove that account eligibility. Card and traveller details are collected by Duffel, rather than entered into chat.

#Built-in weather

Weather (Open-Meteo) is ready without a key for personal non-commercial use. It looks up places, then retrieves current conditions and forecasts with timezone, units, and precipitation probability. Several place matches remain choices rather than being silently guessed. The free API has usage limits; commercial operation requires Open-Meteo's commercial service.

With the general first-party agent loop enabled, these APIs work in ordinary tasks. Structured commands are available in every loop mode:

/shopping.products.search {"query":"shirt","country_code":"GB"}
/shopping.checkout_link {"lines":[{"variant_id":"gid://shopify/ProductVariant/123","quantity":1}],"maximum_subtotal":"40.00","currency":"GBP","country_code":"GB"}
/travel.offers.search {"slices":[{"origin":"BEG","destination":"LHR","departure_date":"2026-10-20"}],"adults":1}
/travel.booking_link.create {"currency":"EUR","flights":true,"stays":false}
/weather.locations {"query":"Belgrade","country_code":"RS"}
/weather.forecast {"latitude":44.8,"longitude":20.46,"timezone":"Europe/Belgrade","forecast_days":3}

Use variant and offer IDs returned by the provider, rather than copying the example placeholder. If multiple stores or travel profiles are connected, choose an exact profile_id when requested.

#Web research

These tools use your existing Brave Search connection. No separate travel or shopping account is needed. If Brave is not connected, open Connections → Brave Search and save its key in the private form. An existing BRAVE_API_KEY or BRAVE_SEARCH_API_KEY also works. Each research request uses one Brave search, followed by at most three public page reads without cookies.

With the general first-party agent loop enabled, try:

Compare one-way flights from BEG to LHR on October 20, 2026, for one adult in EUR.

Compare noise-cancelling headphones under 200 in the UK, including delivery.

Flight research needs airport codes and a departure date. Add a return date for a round trip. Flight-status research needs a flight number and its exact departure date. Results include source links and fetched page excerpts when available. An airline or tracking page must show the requested flight and date before a current fare, status, delay, gate, or connection time can be confirmed.

Product research needs a query and a shopping country. It returns retailer and product sources, with public page excerpts when available. Search snippets are not proof of current prices, stock, delivery to your address, or checkout totals. A blocked page is marked for browser inspection.

Oktapod helps you compare options. You finish the booking or purchase on the airline or retailer website after reviewing the full price and terms. This connector cannot place orders, enter payment details, or spend money.

Structured chat commands work in every agent-loop mode:

/travel.flights.search {"departure_id":"BEG","arrival_id":"LHR","outbound_date":"2026-10-20","currency":"EUR"}
/travel.flights.status {"flight_number":"JU210","departure_date":"2026-10-20"}
/shopping.search {"query":"noise cancelling headphones","country":"uk","max_price":200}

#Google and Microsoft sign-in

Google and Microsoft accounts need a sign-in link that their servers can return to after you approve access. The guided setup handles this. Open Connections → Set up Google & Microsoft, or Settings → Advanced → Open guided account setup, and choose one of:

• Oktapod-hosted sign-in (recommended when offered). It is free and needs no developer console, DNS, or public port. You approve your installation once through an email link. The same email can approve several installations; sign in at account.oktapod.ai to list or revoke them. Tokens reach your Oktapod encrypted to your installation and are kept there. See Privacy and your data for exactly what the hosted service sees.
• Your own sign-in app. Create an OAuth client with Google and an app registration with Microsoft, then paste their IDs and secrets into the wizard. The wizard shows the exact redirect addresses to copy. The return address can be a Cloudflare Worker it deploys for you, Tailscale Funnel, or an HTTPS address you already run.

After that, sign in to each account from its card. The guided picker covers Gmail, Google Calendar, Drive, Docs, Sheets, Google Contacts, Microsoft Mail, Calendar, Contacts, To Do, and Teams transcripts.

By default a Google sign-in asks only for what most requests need: Gmail connects for sending, and Drive reaches the files Oktapod created or you opened with it, plus the Docs and Sheets you name. Reading Gmail needs a permission that Google reviews separately, so Oktapod asks for it only when you need it. Ask to read or search your mail and Oktapod tells you the account is connected for sending only and offers Allow reading, Not now, or Don't ask again. Allow reading opens Connections; confirm and sign in again. Google may say Oktapod isn't verified for that permission yet. If you cancel on Google's screen, Gmail stays send-only and nothing else changes. After Don't ask again, chat only mentions where to allow it: open Connections, choose Google Mail, and select Allow reading. A per-file Google Drive shows Allow full Drive search there too.

Asking for a file without naming an app searches every connected document app (Google Drive, OneDrive, Dropbox, Notion, Obsidian) and says which one each result came from. If nothing turns up and Google Drive is connected for Oktapod's own files only, Oktapod offers Allow full Drive search.

To ask for every Google permission on all new sign-ins instead, including searching all of Drive:

oktapod auth google-access full
oktapod restart

oktapod auth google-access standard turns that off, and oktapod auth google-access shows the current setting. Accounts already connected keep the access Google granted them until you reconnect.

Oktapod reads Google data only when every AI model it uses is a local model, an API account whose terms exclude training, or an account you confirmed has training turned off. Run oktapod models data-use to see which models qualify. If a subscription login such as ChatGPT or Claude is connected, Oktapod asks before the first Google read: chat shows a card for each such account with a link to its training setting and an I've turned it off button, and the Google connections in Connections show the same step. Turn training off there, tap the button, and ask again; no restart is needed. From a terminal, oktapod models data-use confirm <provider> --confirm=TRAINING_OFF followed by oktapod restart does the same.

You can also ask in chat, for example "can you read my Google data?" or "I turned off training in ChatGPT". Oktapod checks right away and asks you to approve before it records a choice.

If you set up your own Google sign-in app, keeping training on is your choice: the card and Connections also offer Keep training on, and from a terminal oktapod models data-use keep-training <provider> --confirm=KEEP_TRAINING.

If you previously confirmed training off in the config file through the CLI, run oktapod models data-use revoke <provider> and restart Oktapod before changing that choice in chat or Connections. Revoking also clears choices saved in the app. With Oktapod's shared Google sign-in that option isn't available, because Google's rules forbid sending Workspace data to models that train on it; use a local model or an API key instead, or turn training off.

#Other kinds of connections

• App passwords and tokens. IMAP, CalDAV, CardDAV, Todoist, Notion, Dropbox, and Home Assistant use a key, token, or app-specific password. Use an app password rather than your main password when the service offers one.
• Notion uses an internal integration token from notion.so/profile/integrations. Oktapod sees only the pages you share with that integration (open a page, then ••• → Connections). To create new pages without naming where each time, paste a shared page's link into Page for new notes. Oktapod adds to existing pages and never replaces their content.
• Teams meeting transcripts need a Microsoft work or school account; personal Microsoft accounts don't offer them. Oktapod finds your recent Teams meetings on your calendar and reads a transcript when you ask, for example "summarize yesterday's architecture sync". A meeting has a transcript only if someone turned on transcription. Your organization's administrator may need to approve the sign-in, and can turn transcript access off for all apps.
• Local folders. An Obsidian vault is a folder on the machine that runs Oktapod. Oktapod only reads and writes Markdown notes inside the folder you choose, never inside hidden folders such as .obsidian, and a new note never replaces an existing one unless you ask for that. On a Mac, if the vault is in Documents, Desktop, or Downloads, allow the Oktapod app's one-time folder access prompt.
• Mac Contacts appears under On this device and needs the Oktapod Mac app. Without it, the card shows Needs Mac app.
• ICS calendar feeds are read-only by nature.

#Several accounts

You can connect more than one mailbox or calendar. Each account is kept separately. Ask Oktapod to search your email and it searches across connected mail accounts. Results keep the account they came from. If a connection fails, Oktapod tells you the search is incomplete. Name an account ("my work Gmail") to search only that mailbox. Reading or sending a message uses one account. When you don't name a sender, Oktapod looks at what it already knows: the message you are replying to, which account you last wrote to this person from, the recipient's organisation, and what the email is about. If that clearly points to one account, the confirmation names it and says why, and you can name another account instead. If it doesn't, Oktapod asks which account to use before confirmation, keeping the recipient and message while you choose. Calendar lookups also span connected accounts unless you name one. A new event goes to one calendar. Read-only sources such as ICS feeds and Calbraid are never chosen for it, so with one writable calendar Oktapod uses that one and names it in the confirmation. With several, it looks at the events you just viewed, the calendar you last used with these people, their organisation, and what the event is for. If that clearly points to one calendar, Oktapod asks you to confirm the event there and says why, even when you gave every detail. Otherwise it asks which calendar to use first.

Each IMAP/SMTP account can also carry a sender name, other addresses it may send from (aliases), and a plain-text signature. Aliases appear as their own choices when Oktapod asks which address to send from; any other address is refused. The signature is added to emails sent from that account unless you ask to leave it off, and JMAP accounts use the signature stored with their server identity. Drafts are saved in the account's own Drafts folder, so they show up in your mail app.

When you reply to a message you looked at in the conversation, Oktapod sends from the account that received it and keeps the reply in the same thread.

Oktapod keeps a small local index of your recent mail (sender, recipients, subject, and a short preview, never full messages or attachments) for the last 90 days, so searches across all your accounts answer almost instantly. It only answers from the index once every account is fully indexed and recently synced; otherwise, and for "latest" or "unread" lists, it asks your providers directly so results are never stale or incomplete.

You can ask Oktapod to archive, move, mark read or unread, or flag mail in any connected account, including IMAP and JMAP mailboxes; it asks before changing anything. When new mail arrives, Oktapod sends a short summary in your main chat, at most once every 30 minutes per mailbox and only outside quiet hours. Connecting an account does not announce its existing mail. Operators can turn alerts off by setting the runtime.mail_alerts.enabled runtime setting to false.

For CalDAV, the server address is enough (for example https://cal.example.com). Oktapod asks the server for your calendar the standard way and remembers the answer. If the account has more than one event calendar, it asks you to enter the URL of the one to use. A full calendar URL also works.

For IMAP and SMTP accounts, your email address and app password are usually enough: leave the IMAP and SMTP hosts blank and Oktapod finds them when you connect. It knows the common providers (Gmail, iCloud, Yahoo, AOL, Zoho, Fastmail, GMX), then reads your domain's published mail settings, then its mail DNS records. A custom domain hosted elsewhere, including Google Workspace, is found through the domain's mail server. Only encrypted servers are accepted. The connected account shows the hosts it will use; if nothing is found, Oktapod asks you to enter them. A host you enter is kept with the port and encryption you give it.

Outlook.com, Hotmail, and Microsoft 365 mailboxes no longer accept app passwords over IMAP (Microsoft's server answers "Login is disabled"), so Oktapod tells you to connect them with Microsoft Mail sign-in instead. If a mail server later rejects an app password, the account is marked as needing reconnection and you get one notice in chat with the server's reason.

When you enter hosts yourself, use the ports supplied by your mail host. Oktapod uses direct TLS on IMAP 993 and SMTP 465, and requires STARTTLS on IMAP 143 and SMTP 587 or 25. Both modes encrypt the connection before authentication. For a custom port, set the account's IMAP or SMTP encryption field to tls or starttls. Leave it as auto for standard ports. Certificate checks remain enabled; a server that cannot establish encryption fails the connection.

After an IMAP/SMTP send, Oktapod keeps a copy in the mail server's Sent folder. You can set an existing folder in the account's Sent folder field if your server does not mark one. If the server already saved the message, Oktapod keeps that copy. If saving fails, the delivery result still says the message was sent and reports the missing copy. Repeating that action does not send another email or append another copy.

SMTP submission is recorded before it starts. If the connection ends without a clear delivery result, Oktapod reports uncertainty and blocks an automatic resend. Check Sent or the recipient before asking for another send. A rejected sign-in asks you to reconnect the account. Delivery and Sent-copy state remain separate from the account's connection health.

JMAP mail can be added from Connections or oktapod setup email. Supply the HTTPS session URL and an app password with a username, or choose bearer for an API token. Leave the server account ID blank for its primary mail account. For browser sign-in, register your own OAuth client with the mail host. Set jmap_oauth in your private oktapod.json, then choose JMAP Mail sign-in in Connections. Register the exact callback URL from the sign-in link with your host. The default is <your-callback-host>/oauth/jmap-mail-oauth/callback; the existing callback relay can carry this callback too.

{
  "jmap_oauth": {
    "base_url": "https://mail.example.com/.well-known/jmap",
    "authorize_url": "https://auth.example.com/authorize",
    "token_url": "https://auth.example.com/token",
    "oauth_origin": "https://auth.example.com",
    "client_id": "your-registered-client-id",
    "scopes": ["urn:ietf:params:oauth:scope:mail", "offline_access"]
  }
}

Use the scopes your host requires. Public clients use PKCE. Confidential clients also set client_secret_ref to a private file or environment secret reference. Token exchange uses client_secret_post. Never paste a client secret into the registration. The configured OAuth origin may differ from the mail origin. Redirects are refused and mail access tokens stay on the mail origin. Changing the registration during sign-in requires a new sign-in. Each authorized mail account gets its own durable profile. You can also import an already-consented renewable grant with oauth2, token_url, and an optional separate oauth_origin.

JMAP supports search, message reads, threads, folder lists, attachment downloads, drafts, and sending with attachments when the server grants submission access. Sending uses a registered server identity and requires confirmation. Attachments follow the same size limit and blocked file types as other mail accounts. Its session and API must use the same HTTPS origin; redirects to another origin are rejected.

Calbraid can be connected from Connections or oktapod setup calendar using its HTTPS service URL and a personal API token with calendar:read scope. Lookup preserves the original calendar name and provider. Calbraid writes are not yet supported by this connector.

#Attachments and encrypted mail

When Oktapod reads an email it gets the message text, the list of attachments, and whether the message is encrypted or digitally signed. It never receives a whole raw message with every attachment inside it.

Opening an attachment is done safely. Oktapod extracts the text of PDFs, plain text files, and Word, Excel, and PowerPoint documents, and treats that text as something the sender wrote, never as instructions to follow. It never runs or renders a file. Programs, scripts, installers, and disk images are refused outright, even when renamed to look like a document. Files matching a known malware test signature are refused too. Archives are not unpacked. Macro-enabled Office files have their text read without running the macros. Opened files are kept for 30 days, so the runtime's own safety scan and image or scanned-PDF understanding can run on them.

An encrypted message (S/MIME or PGP) or a password-protected attachment is reported as encrypted. Oktapod holds no keys or passwords, so it tells you to open those in a mail app that has your key. It doesn't guess at the content. A signed message is noted as signed; Oktapod does not verify signatures.

#Keep connections healthy

Each card shows a status:

Oktapod keeps email and calendar sign-ins alive on its own. A Google or Microsoft account you haven't used for a few days gets a quiet token refresh, so it doesn't lapse from inactivity. If a provider rejects Oktapod's access, for example because you revoked it or changed an app password, Oktapod sends one message in your main chat naming the account and how to reconnect it. A temporary outage never triggers that message; Oktapod waits and tries again. If an account works but hasn't approved a permission Oktapod now uses (for example, after an update adds drafts and replies for Microsoft mail), the account keeps working for everything else and you get one message asking you to sign in again to approve it. Microsoft To Do accounts connected before Oktapod could add tasks are one example: they keep listing tasks until you sign in again and allow changes.

If a sign-in expires or is revoked, open the card and sign in again. If a connection is valid but calls still fail, check the provider's billing, subscription, or admin consent before replacing credentials.

#From the terminal

Focused setup commands add one account without redoing the rest of setup:

oktapod setup email
oktapod setup calendar
oktapod setup documents

Check and repair sign-ins:

oktapod auth status
oktapod auth login --provider google-mail
oktapod auth logout --provider google-mail

Replace google-mail with the provider you need, such as google-calendar, microsoft-mail, or google-drive. oktapod auth providers lists them.