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 reads and proposes changes only inside those folders.

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.

The AI is locked to the scoped portal(s). It can touch files inside those connected folders and nothing else: not the rest of your computer and not the rest of your workspace. That boundary is automatic.

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.

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.

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.

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. Everything is undoable. One click undoes a whole run of changes, deletions included.

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.

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.