Last updated

Setting up AI

Undra’s AI can chat with you, work inside your notes and plans, and run agents you control. 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 ChatGPT or Claude, 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

Open Settings, find the AI section, and switch on Enable AI.

This is just the master switch. It 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.

Step 2: Choose how Undra connects to AI

Once AI is on, click Open AI page (the button is right there in Settings) and go to Providers. You’ll pick one of two kinds.

Use a subscription

Already pay for ChatGPT or Claude? 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 ChatGPT or Claude, 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 ChatGPT or Claude 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 ChatGPT (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 “Codex CLI detected” when it’s 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.

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.

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.

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 and dashboards 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 or dashboards.
  • 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 ChatGPT, sign in for Claude), 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