Folder Portals

A folder portal links a real folder on your computer into Undra as a connected work zone: you and Mira read and edit those files where they live, scope a chat to the project, run a dev server, and preview the result without copying anything into the workspace.

This is how you point Undra at an existing code project, a folder of notes, or a messy downloads directory, and start building with AI context grounded in real files.

What a portal is

• A link, not a copy. The portal is a live connection to a real folder. Edit a file through Undra and the file on disk changes. Change the file on disk and Undra sees the new version.
• Real files only. Portals hold ordinary filesystem files: code, docs, assets, configs. You cannot put Undra notes, plans, or canvases inside a portal. That boundary is enforced automatically.
• Your files stay yours. Undra does not move your folder into its own storage (for external portals). It just gets permission to read and write inside that one folder.
• Desktop only. Folder portals work in the Undra desktop app. They are not available in the web demo.

Scope a chat to a portal

You do not have to open a chat inside the portal folder. Attach one or more portals to any chat with a Scope pill in the composer:

1. Click Scope (or the scope area) in the chat composer.
2. Pick the portal folder(s) you want this conversation grounded in.
3. Send your message. The AI is grounded in those folders: it reads there and directs its changes there.

Opening a chat from inside a portal folder still works and scopes the chat automatically. Scope pills are the flexible option: keep a general workspace chat open and point it at a code project when you need to.

Scoping anchors the AI’s attention; the hard limits on what its file tools can touch are separate and automatic. Undra’s file access stops at your workspace, your connected portals, and folders you explicitly approve - the exact boundary, including its two deliberate carve-outs, is spelled out in What Undra is allowed to reach below.

Let the AI work in it

With a portal scoped to the chat, the AI can:

• Read any file in the folder to understand what is there.
• Propose changes: create new files, edit existing ones, rename, move, or delete.
• Run a dev server for web projects and open a live preview tab that reloads as files change.
• Check its own work on localhost pages. For portal projects, Mira can open the running preview, look at the result, and fix what is off instead of editing blind.

House rules with AGENTS.md

A portal can carry standing instructions in an AGENTS.md file at its root: coding conventions, tone, folders to leave alone. Whenever the AI works in that portal (from a scoped chat or from a chat opened inside the folder), those rules are included automatically.

You can add or edit the instructions right inside Undra (the portal shows a small badge next to its name once they exist), and because AGENTS.md is a convention many coding tools share, a project that already has one just works. If a project keeps its house rules in CLAUDE.md instead, Undra reads that too. Neither file is ever written to: they are yours.

Portal notes, UNDRA.md

AGENTS.md is what you tell the AI. UNDRA.md is the other direction: the AI’s own working notes about the folder, kept in a plain file at the folder root so you can read, edit, or delete them like anything else. What it learned about the build, a decision it made, a landmine to avoid next time - it lands there and travels with the folder.

The two files have different owners and never mix. Mira writes UNDRA.md and will not rewrite your AGENTS.md. A connected outside AI tool reads and adds to the same notes, so knowledge carries between them.

Preview files and dev servers in Undra

Click any file inside a portal and it opens right in Undra, not your system’s default program:

• Web pages render live, with a Reload button and an “Open in browser” escape hatch.
• Images, PDFs, video, and audio play inline.
• Text and markdown files show up readable, right in the tab.
• Anything else gets a simple card telling you so, with a button to open it in your default app.

For runnable projects (a package.json with a dev/start script, or a Vite config), right-click the portal and choose Launch dev server. Undra starts the project, waits for the localhost URL, and opens a preview tab tied to that server. Edits from Undra or from any external editor reload the preview. Close the tab to stop the server.

Double-click a file instead of single-clicking and it always opens in your system’s default program, no matter the type.

Documents Mira can read

A connected folder is often full of things that are not code or notes: contracts, research papers, spreadsheets, decks. Mira reads the text inside them, so you can ask questions about a folder of documents instead of opening each one yourself.

These formats are read for their text:

Pages, sheets and slides keep their labels, so an answer can tell you it came from page 12 or the Revenue sheet rather than pointing vaguely at the file.

Everything happens on your computer. Nothing is uploaded to read a document.

Finding the right document

Reading a document assumes you know which one to open. In a folder of two hundred contracts you usually do not.

Ordinary text search cannot help here, because the text inside these files is compressed and there is nothing readable for it to match. So documents are found by meaning instead. Ask for “the contract with the payment terms” and the right file comes back, even when those words appear nowhere in its filename.

This uses the same local index as the rest of connected-folder search, so it needs to be built once for that folder and runs entirely on your machine. Documents added later appear after the index is rebuilt.

Connect a folder

There are two ways to create a portal:

1. From the command palette. Open it with Ctrl/Cmd + K, search for Connect external portal…, and pick any folder on your computer.
2. By dragging. Drag a folder from your file manager (Finder or Explorer) straight onto the Undra window.

Either way, Undra shows a short permission prompt with the exact folder path, then adds the folder to your sidebar, named after the folder itself. Expand it to browse the real files inside.

Internal vs external portals

Every portal folder shows a small badge next to its name:

• External portal · <path> (accent-colored): the files live somewhere else on your computer, at the path you originally connected, shown right in the badge. Undra records the connection in .undra/portals.json inside your workspace.
• Workspace portal (neutral): the files live in a real directory at .undra/portals/<name> inside your workspace, so they travel with your workspace backups.

If Undra loses track of a portal’s files, the badge changes instead: Portal · Missing means the connected folder can’t be found (moved, renamed, or on a drive that isn’t attached), and Portal · Needs access means Undra still knows where the folder is but has lost permission to read or write it.

You can also create a workspace portal by name (for example, “create a portal called Assets”) without picking an OS path first. The AI can do this for you, or you can create a new managed folder through the same connect flows above.

You can also move a connected folder to another workspace entirely: right-click it, pick the destination workspace, and the folder travels with its files, its AGENTS.md house rules, and its UNDRA.md notes intact. It can never end up registered in both places at once.

If you want an external portal’s files centralized with the rest of your workspace, right-click it and choose Move into workspace. Undra moves the real files into .undra/portals/<name> and keeps the portal working exactly as before. The AI, your chats, and everything you had open still point at the same folder. The files leave their original location, so if that location was synced (OneDrive, Dropbox, and similar), they stop syncing there, and anything outside Undra that referenced the old path will need updating.

How changes stay safe

This is the part that makes portals comfortable to use. Every change is listed in chat, backed up when needed, and undoable.

1. The AI lists the change set. You get a card in chat that shows every file touch, with sizes.
2. Changes apply right away. Creating, editing, renaming, moving, and deleting all land as the AI works, so you are reading results instead of clicking through a queue.
3. Anything destructive is backed up first. Before a file is overwritten or deleted, Undra copies it into its own app data, outside your project folder.
4. File changes are undoable. One click undoes a whole run of file changes, deletions included. Terminal commands the AI runs (installs, builds, scripts) are not file edits, so their effects are not reverted by undo.

Trust here comes from reversibility, not from an approval wall: the safety you are relying on is the backup taken before the change and the undo that puts it back, not a prompt you have to answer.

What Undra is allowed to reach

Undra can read and write inside a fixed boundary: your workspace, the folders you have connected as portals, and any folder you have specifically granted. Undra’s file access, including Mira’s own file tools, does not reach outside that boundary.

Two deliberate carve-outs, stated plainly rather than implied away: terminal commands the AI runs are not confined to that boundary (confining a command safely would need an operating-system sandbox, and pretending otherwise would be worse than saying so), and external tool servers (MCP) you add are separate programs with their own permissions. The boundary governs Undra’s own file access.

Granting a folder

Hand Mira a path outside that boundary, a PDF sitting in Downloads for instance, and she cannot open it. Instead of failing silently she asks, and you get a prompt with two ways to say yes:

• This session lets her reach the folder until you quit Undra. Right for a one-off look.
• Always records the folder permanently.

Only your click grants anything. Denying, or ignoring the prompt until it times out, refuses the request. Some places can never be granted at all, whatever the prompt says: drive roots, system folders, Program Files, and the root of your user profile.

Reviewing and revoking

Open Settings, then Workspace, then Folder access to see every folder you have granted, along with what is currently using it. Each row offers Remove access, and the confirmation tells you what actually happens: a portal backed by that folder stops working, and nothing on disk is deleted.

Folders that have gone missing, an unplugged drive or a deleted directory, can be cleared in bulk. A granted folder you have not connected yet can be turned into a portal from the same place.

Grants are stored per installation and shared by every workspace on the machine, so this list is not something that resets when you switch workspaces.

The Portals view

The sidebar shows your connected folders as a tree, which is right when you know what you are looking for. When you want to see everything you have connected at a glance, open Portals from the bar on the left.

Each folder appears as a card showing what kind of project it is, when you last opened it, and small badges for the two files that matter: its house rules (AGENTS.md) and its portal notes (UNDRA.md). If the folder tracks its history, the card carries its branch and how many files have changed.

From a card you can open the folder, preview it, or run it. A folder holding a web project offers a preview; one holding a desktop app offers Run instead.

Remove a portal

What removing looks like depends on where the portal’s files live.

External portals: right-click and choose Disconnect portal. Undra stops mirroring the folder and gives up its access. Your real files on disk are never touched. They stay exactly where you always kept them.

Internal portals (files in .undra/portals/<name>) offer two choices instead, so files can never be left behind somewhere you cannot see:

• Move out of workspace…: pick any folder on your computer and the files move there. The portal keeps working and simply becomes external again.
• Delete portal: the files move into Undra’s own Trash, recoverable from the Trash view (they live on disk under .undra/portal-trash) until you clear them. Never silently erased.

What portals are good for

• Work on a real project in place. Point a portal at a code or writing project and ask the AI to make a change across several files at once, then review and undo in one click if you do not like it.
• Reorganize a folder. Aim a portal at a pile of loose files or notes and have the AI sort, rename, and tidy, with every move backed up.
• Bring a folder into your thinking. Browse and reference real files next to your notes, plans, and canvases, without copying them in.

Good to know

• Desktop app only, not the web demo.
• Real files only: notes, plans, and canvases cannot be created inside a portal.
• Large folders show up to 500 items per folder in the sidebar. The AI can still read everything in the folder beyond that.
• Backups never touch your folder. Pre-edit backups live in Undra’s own app data, not inside the portal, so they never show up in git status or sync along with your project. They are kept for 7 days.
• Portals show every file. They do not hide things based on a .gitignore, so everything in the folder is visible and editable.
• Click to preview, double-click to open externally. See Preview files and dev servers in Undra above.

Where to go next

• Chats: Scope pills and the full chat experience.
• Mira: the assistant who does the work inside a portal.
• Local-First Trust: why working on your real files is safe by design.
• Importing & Adopting: the other way to bring existing files into Undra.