External agents (Beta)

Last reviewed: 2026-11-20

An external agent is an AI program of another maker — an agent you installed on your computer and signed in to yourself, with your own subscription or key. Plainva can start such an agent in the folder of a vault and show its session in the AI tab. This is part of the experimental AI features and works on the desktop only.

An external agent is not Plainva’s assistant. The AI Assistant sends only what its overview showed you, and never what your privacy rules keep back. An agent reads and sends on its own. This page says what Plainva controls in such a session — and what it does not.

What Plainva does not control

Start an agent only in a vault whose content may reach the agent’s service.

What Plainva controls

Adding an agent

  1. Install the agent yourself, the way its maker describes, and sign in to it in its own program.
  2. Open Settings → AI. In the card Other programs, under External agents, Found on this computer marks the agents Plainva knows by name and finds installed; Add adds one. For any other program that speaks the Agent Client Protocol, choose Add agent… under Another agent and enter a Name, the Program and its Arguments, one per line.
  3. Your system shows the whole command once more before it is remembered.

Plainva installs no agent and downloads none. It starts exactly the program you confirmed, directly and without a shell. The command is remembered on this device, never in the vault. Remove makes Plainva forget how to start an agent; the program itself and its sign-in stay as they are.

Starting a session

Open the AI tab and choose Agent. Before anything starts, Before you start ⟨agent⟩ lists what the agent does on its own and what Plainva controls, and says whether Plainva’s tools will be offered. Start session starts the agent’s program in the vault’s folder. The first time you start an agent in a vault since Plainva was opened, your system asks once more, showing the folder and the whole command.

One session runs at a time, and it belongs to the vault it was started in: End session stops the agent’s program, and so does closing the vault or Plainva. For as long as it runs, the first line of the session says who the agent is and that your privacy rules do not apply to it. No agent is started inside an encrypted workspace.

Signing in

An agent that is not signed in says so, and the session shows ⟨agent⟩ wants a sign-in with the ways the agent names. Depending on the agent, choosing one opens a terminal window with the agent’s own program, or the agent takes you to its sign-in itself. Plainva waits and, after a sign-in in a terminal, starts the agent anew; where the agent signs in itself, it goes on in the same session. Where no terminal can be opened, Plainva shows the command to run in a terminal of your own; afterwards choose Try again. Plainva sees nothing of the sign-in.

In a session

Type what the agent should do. The note you have open is named to the agent — its name and where it lies, not its text — unless you remove it above the input; a note you keep from the cloud or from the internet is never named. The session shows what the agent says, its plan and each of its steps, with the files of the vault it names.

When the agent wants your leave for a step, ⟨agent⟩ asks shows it. The words are the agent’s own, and so are the choices: the buttons carry the names the agent gives them — only where it names none do you see Allow, Always allow, Reject or Always reject. Your answer goes to the agent only: what it does after a yes is its own doing, and an “always” is the agent’s promise to keep, not Plainva’s.

Settings and commands. Where the agent offers them, the foot of the session shows its own settings: its mode and its model as buttons — ⟨setting⟩: ⟨value⟩ —, the rest behind the sliders button More settings of ⟨agent⟩. Each of their menus begins with Plainva’s own heading — ⟨setting⟩ of ⟨agent⟩, or More settings of ⟨agent⟩ —; below it, names, values and descriptions are the agent’s own, in its order: the current value with a tick, a switch as an entry with or without one. Wherever the agent’s words stand in a heading or a sentence of Plainva’s, they are set apart in quiet italics, never in the heading’s capitals. Each session starts with the agent’s defaults. A setting changes how the agent works, not what Plainva lets through: reading and writing through Plainva follow the same rules whatever the mode, and a mode in which the agent asks nothing more saves none of Plainva’s own steps. What the agent does with its own tools is outside Plainva in every mode. When the agent changes a setting by itself, the session says so: The agent set “⟨setting⟩” to “⟨value⟩” itself. What it changes along with a change of yours, the session names as such — With it, the agent set “⟨setting⟩” to “⟨value⟩”. —, and a change the agent did not make, too: The agent did not change “⟨setting⟩”. While a change waits for the agent, a spinner turns beside the settings, and they take no press until it answers. Typing / at the start of a message lists the agent’s own commands under Commands of ⟨agent⟩, with what it says they do: the arrow keys move through the list, Enter or Tab takes a command, and Escape closes the list. A command is a message that begins with its name; where the agent says what goes after it, that stands under the field until you type on. What a command does is the agent’s matter.

Stop ends the answer the agent is working on.

What the agent writes

Through Plainva. A change the agent hands to Plainva is never written into the note. When the agent’s answer is finished, every note it changed carries one round of suggestions, signed ⟨name⟩ (external agent): under Suggestions you accept or decline each change or the whole round, as with a round from a person. A property the agent’s text changes stands in that round as a proposed value, like one Plainva’s own assistant proposes. A note that does not exist yet waits as a draft — a card Draft · Note in the session, and the same card in the list To decide of the AI tab, where it stays when the session has ended. Create writes it at exactly the place the agent named — marked generated, with the agent as its author — and Discard drops it. Web addresses the agent brought along are written so that nothing opens or loads them (https[://]…).

Plainva does not take everything: only Markdown notes; no AI rules, no trust fields and none of Plainva’s own properties; no property value that is neither text, a number, yes or no, nor a list of those; nothing that is kept from the cloud or from the internet; no more than 150 changes to one note at a time; and no further new note while too many drafts are waiting. What it did not take, the session says, and the agent is told.

By itself. An agent can also write files on its own, like any program. When it reports such a change, the session says The agent changed ⟨note⟩ itself: it is in the vault without a suggestion. Which way an agent takes is not Plainva’s to promise: it depends on the agent and on how it is set up. In the settings, each agent shows what was last seen on this computer — how many changes came through Plainva and how many it wrote itself.

What Plainva keeps

If the agent’s program ends by itself, the session says so, and Show its last lines shows the end of what the program wrote.

Limits