Last updated

Setting up AI

Undra’s AI can chat with you as Mira, work inside your notes and plans, and make changes you can see and undo. This page takes you from “off” to “talking to AI” in a few minutes, then shows the optional extras when you want them.

The short version

Three steps and you’re going:

  1. Turn AI on in Settings.
  2. Connect a provider: a subscription you already pay for, or a free app on your own computer.
  3. Pick a model and start chatting.

That’s the whole core flow. Everything below is detail and optional add-ons, so feel free to stop reading once you’re chatting.

What “AI” actually means here

Undra does not have its own built-in AI brain. It connects to one you choose, called a provider. A provider can be a paid service like OpenAI, Claude, or Cursor, or a free app that runs AI right on your computer. You pick which one, and your data follows the rules of whatever you choose.

Step 1: Turn AI on

The master switch lives in Undra Home, the launcher, not inside a workspace. Open Settings there, go to App, and switch on Enable AI features.

That one switch reveals the AI chat, the AI button in the sidebar, and the inline AI actions. It does not send anything anywhere on its own. Turn it off and all of that is hidden again, while any settings you saved are kept for next time. AI settings are app-wide, so this applies to every workspace, which is why it lives with the launcher rather than in one workspace’s settings.

Step 2: Choose how Undra connects to AI

With AI on, the AI sections appear in the Settings sidebar, both in Undra Home and in any workspace. Go to Providers. You’ll pick one of two kinds.

Use a subscription

Already pay for OpenAI, Claude, or Cursor? Use it. This is the fastest path if you have one. Your messages go to that company’s servers.

 Keep it all local

Want it free and fully private? Run AI on your own machine with a free app. A little more setup, and nothing ever leaves your computer.

Not sure which?

If you already pay for OpenAI, Claude, or Cursor, the subscription path is quickest. If you don’t, or you want everything to stay private, the local path is worth the small extra setup.

Use a subscription you already pay for

Undra connects to OpenAI, Claude, or Cursor through the official command-line tool each company provides. You install that tool once, sign in, and Undra detects it for you. No separate API key needed: your subscription login is all it uses.

For OpenAI:

  1. Install the Codex command-line tool (the Providers page links to the guide).
  2. Run codex login once and sign in.
  3. Reopen the Providers page. Undra shows “Detected” when it is ready.

For Claude (Anthropic):

  1. Install Claude Code (the page links to the quickstart).
  2. Sign in.
  3. Reopen the Providers page. Undra detects it the same way.

For Cursor:

  1. Install the Cursor CLI (the Providers page links to the guide).
  2. Run cursor-agent login once and sign in.
  3. Reopen the Providers page. Undra detects it the same way and uses your Cursor plan.

Where your data goes

With a subscription provider, the text of your messages, plus any context Undra attaches, is sent to that company to generate a reply. That is normal for cloud AI. If you would rather nothing left your machine, use the local option instead.

Keep everything on your computer

Prefer privacy, or don’t have a subscription? Run a model locally with a free app. Undra works with two popular ones:

  • Ollama, simple and widely used
  • LM Studio, a friendly app with a built-in model browser
  1. Install Ollama or LM Studio.
  2. Download a model inside that app (for example, llama3 in Ollama).
  3. Start it. Ollama runs at http://localhost:11434 and LM Studio at http://localhost:1234.
  4. In Undra’s Providers page, choose the local provider. Undra detects it once it’s running, and you type in the model’s name.

Everything runs on your machine, nothing is uploaded, and it works offline. The trade-off is that local models need a reasonably capable computer, and smaller models are not as sharp as the big cloud ones.

Step 3: Pick a model and start chatting

On your provider’s card, choose a model from the dropdown, or type one in. This is just the default for new chats, and you can change it whenever you like. In chat itself, one picker lists the models from every provider you have connected, so you can switch between them (say a local model and a cloud one) without coming back to this page.

Now open the AI chat from the sidebar and say hello. You’re set up.

Don’t overthink the model

The default is a sensible balance of quality and cost. Try it first, then switch later once you know what you prefer.

Usage and cost

The AI page has a Usage tab that keeps track of what you’ve been spending. It shows your number of requests, the volume of tokens used, and an estimated cost, broken down by profile, model, and surface (chat, inline actions, and so on) so you can see where the spend is going. The AI Overview shows a recent rollup at a glance.

Usage reflects interactive chats and background fan-out runs Mira starts for bigger jobs, not only the messages you type.

What Mira remembers

As you chat, Mira builds up a small set of long-term memories: durable facts and preferences it carries into later conversations, so you do not have to re-explain yourself each time. You stay in control of them. Open the AI page and go to Memory to see everything Mira has saved, approve or dismiss the memories it suggests, pin hard rules it must always follow, and clear anything you do not want kept.

Memories are stored as ordinary notes in a Mira/Memory folder in your workspace, so they are yours to read and edit like any other file. See What Mira remembers for the full picture.

Optional: connect external tool servers (MCP)

Beyond Undra’s built-in tools, you can add external MCP servers: stdio programs that expose extra capabilities (Blender, a database CLI, a custom script, and so on). Open the AI page (via Settings → AI → Open AI page, or the sidebar) and go to MCP Servers to manage them.

Add a server

  1. Open the AI page and go to MCP Servers.
  2. Click Add server, give it a short id (lowercase letters, digits, hyphens only, no underscores), and enter the launch command (for example uvx blender-mcp).
  3. Confirm the dialog that shows the exact command. Adding a server can run code on your machine, so Undra always asks before a new executable is trusted.
  4. Enable the server. Its tools appear on your next chat turn as mcp__<id>__*.

Mira can also add or list servers for you via chat when you ask to hook up a tool. You still get the confirmation dialog for new servers.

Reserved ids

The ids undra, mcp, and builtin are reserved. Undra’s own bundled tool server always loads last so it cannot be shadowed by a user entry.

Who gets the tools

Once you trust an MCP server, Mira and ordinary dock chats attach its tools automatically on the next turn. One-shot inline AI (ghost text, summarizer) never attaches external servers, even if they are enabled globally.

Security notes

  • External MCP children never receive Undra’s automation-bridge token.
  • One-shot inline AI (ghost text, summarizer) never attaches external servers, even if they are enabled globally.
  • Local models (Ollama, LM Studio) do not support external MCP in the current release.

Optional: smarter search across your notes

By default, Undra’s chat searches your workspace by keyword. If you want it to search by meaning instead, so a search for “money coming in” can find a note titled “Revenue,” turn on semantic search.

Open the AI page and go to Semantic Search. This runs entirely on your own computer: a small local model converts your notes and plans into the number form that powers meaning-based search. No API key, no provider, and nothing is sent to any server. Then:

  1. Click Build index. Undra reads your notes and plans, converts them on your machine, and stores the result locally in .undra/embeddings.sqlite. The first build downloads the small model once, so keep the app open until it finishes.
  2. From then on, search and chat can find things by meaning, not just exact words.

Semantic search stays on your machine

Unlike cloud AI chat, semantic search never leaves your computer. The model that builds the index runs locally, the index lives on your machine in .undra/embeddings.sqlite, and every search matches against that local file. There is no API key, no provider, and no usage cost, and it works offline once the model has downloaded the first time.

  • Only notes and plans are indexed. Canvases are not included.
  • Built once, then kept in sync. The vectors are stored locally and updated as you edit; nothing is uploaded at any point.

A few things worth knowing:

  • Only notes and plans are indexed, not canvases.
  • It runs on your machine, so there is no API key, no provider account, and no usage cost.
  • The index keeps itself up to date as you edit, and you can test it right on the page before relying on it.

What is an “embedding”?

An embedding turns a piece of text into numbers that capture its meaning, so the computer can match ideas that are worded differently. You do not need to understand the math, just that it makes search smarter.

Optional: AI for images, fully on your computer

Undra can also work with your images on-device: find pictures by what’s in them, pull text out of screenshots, and more. These models run entirely on your machine, so nothing is uploaded.

Open the AI page and go to Media AI (local). Undra checks your hardware and recommends one of two bundles:

  • GPU (faster): about 1.1 GB on disk, 580 MB to download. Recommended if your computer has a capable graphics card.
  • CPU (works anywhere): about 2.2 GB on disk, 1.1 GB to download. Slower, but runs on any machine.

Pick the recommended one, click install, and Undra downloads the models once. After that, the image features work offline.

Which should I choose?

There is no wrong answer. A quick comparison:

Subscription (cloud) Local app
Setup Install one tool, sign in Install an app, download a model
Cost Your existing subscription Free
Privacy Messages go to the provider Nothing leaves your computer
Quality Top-tier models Good, depends on the model and your hardware
Works offline No Yes

Plenty of people use a subscription for everyday chat and local models for private or offline work. You can set up both and switch between them.

If something isn’t working

  • A cloud provider says “Needs setup”: make sure you installed its tool and signed in (codex login for OpenAI, sign in for Claude, cursor-agent login for Cursor), then reopen the Providers page so detection runs again.
  • Local provider not detected: check that Ollama or LM Studio is actually running. If you changed its port, set the matching server URL in Undra.
  • Local model not responding: confirm you downloaded a model in the app and typed its exact name in Undra.
  • Semantic search is greyed out: build the index once on the Semantic Search page. The first build downloads a small local model, so keep the app open (and online for that one download) until it finishes.

Where to go next