Persistent agents: agents that keep their conversation¶

A persistent agent is an agent that runs on your computer and keeps its conversation between the times you talk to it. You start it, talk to it and stop it. When you start it again, the conversation continues where it stopped. It also keeps its own files, and it shares one folder with you.

Agentry has three. They are built into the CLI and the app. You do not install them from a registry: a persistent release listed there does not give you the agent, and the runner refuses to run it as an ordinary QuickAgent.

Agent	CLI name	Runs in	For
Agentry Helper	`main`	Agentry Desktop only	Finding, installing, running and scheduling QuickAgents from a card on Home
The Assistant	`assistant`	Agentry Desktop and the CLI	A personal assistant that keeps notes and files and remembers you
The Coding agent	`coder`	Agentry Desktop and the CLI	Writing, building and running software, and deploying it

This page describes Agentry Desktop 0.6.149 and CLI v0.6.157; an earlier version lacks some of it, and the sections say which. They run in containers, on the model your runner policy names, so they need a container engine and a model set up in Agentry Desktop (Settings → Provider) or with agentry setup. The first start of an agent can take several minutes while Agentry pulls and builds the images it needs.

How a persistent agent runs¶

Segments. Each start-to-stop is a segment, an interactive session with its own receipts. The conversation carries across segments.
No session caps. An agent has no idle timeout, no time limit and no turn limit. It runs until you stop it.
Two volumes. The conversation lives on one volume of the agent's own and its files on another. Stopping the agent keeps both. Only a reset removes them.
One owner at a time. Agentry Desktop or the CLI runs an agent, not both. The other refuses to start it and names the holder. The app shows the agent as "Running in" the holder's name.
The conversation continues. A new segment asks the model's harness to load the stored conversation. If the harness cannot, Agentry gives the agent the last exchange from the transcript instead (each side cut at 4,000 bytes), and the segment's record says why.

Agentry Helper¶

Agentry Helper is Agentry's own assistant. It lives in a card on Home in Agentry Desktop and runs only there. In the CLI, agentry agent list shows it as "desktop only", and every agentry agent command but list and show refuses it.

Opening Home starts nothing. Your first message in the card starts the agent and turns it on: it is on while its card is. Settings → Home shows or hides the card. The first time, a dialog asks you to agree to the agent's share folder, ~/agentry/mainshare by default. With no model set up, the card says so and links to Settings → Provider.

Ask it in plain words. It can search the registry and show you a QuickAgent, install one, run an installed one on files you put in its share folder, add, list, pause, resume and remove schedules, open a section of Settings, and answer from the pages of https://docs.secureagentry.net. It does not change a setting, start or stop another agent, publish, sign in or touch a key.

Each call goes through the operation and the consent the app uses when you do the same yourself:

An install asks in the install dialog, which names Agentry Helper as the one asking.
The first time it runs a version of a QuickAgent, the app asks. The dialog names the files and quotes the task the agent wrote. Later runs of that version ask nothing. An update asks again.
Adding or removing a schedule asks. Pausing, resuming and listing do not.
A run it starts is an ordinary run, in Recent runs, writing to your output folder. It holds the run lock like any run, so the request is refused while another run is in progress.

Agentry Helper stops when the window closes to the background (see Running in the background). In Settings → Persistent Agents it has Start, Stop and Reset only.

The Assistant¶

On its first conversation the Assistant asks you for a name and a personality and saves your answer through its one Agentry tool, which changes its name and personality and nothing else. You can change both later in its Configuration. It keeps notes in its own files and reads and writes the files in your share folder. You can give it knowledge packs and MCP servers (see The roster). It has no network access, commands or secrets of its own, and it runs in the sandbox every run has, with no route out but the model's.

Folders¶

An agent has two places for files.

Its share folder, which it shares with you, read and write: you see what the agent writes there as it writes it. The default is ~/agentry/assistantshare for the Assistant, ~/agentry/codingshare for the Coding agent and ~/agentry/mainshare for Agentry Helper. The first start makes it. The agent sees it as share/.
Its own files, on its data volume, which it sees as data/. It keeps its notes and projects there. The volume is kept until you reset the agent.

To choose another share folder, use Choose a folder… in the agent's Configuration, or agentry agent configure <name> --share <folder>. Use its default puts it back. Agentry refuses a folder that is not an absolute path or is reached through a link, a filesystem root, your home folder or a folder that holds it, a hidden folder of your home folder (such as ~/.ssh) or anything inside one, the runner home, Agentry's configuration or a folder that holds either, and a system folder outside your home folder and your mounted volumes.

Add file on an agent's page copies the files you pick into its share folder. It never writes over a file that is there.

Malware check. For Agentry Helper and the Assistant, Agentry checks the files in the share folder with ClamAV before each turn: those that are new or changed, up to 2,000 files and 512 MiB a turn. The agent reads a file only after the check passes it. A file ClamAV finds is refused, and the refusal names the signature. A file ClamAV cannot check (no signatures on your computer, or a file past its limits) is read unchecked, and the chat says so. A file you add while the agent is answering waits for the next turn. The Coding agent reads its share folder as it is, with no check, and runs what you put there. Give it a folder of its own.

The roster¶

An agent's roster is everything it has. Each entry has a kind, a state (On, Off, Applies at the next turn or Needs a sign-in), who added it (built-in or added by you) and a sentence that says what it gives the agent. In the app the roster is on the agent's page, under Tools and servers, and in Configure → What it has, grouped as Folders, Tools, Dev server, Ports, Knowledge packs and MCP servers. In the CLI, agentry agent show <name> prints it.

The entries are:

share, your share folder. On by default. You can switch it off.
data, its own files. Always on.
knowledge:<pack>, a knowledge pack kept on this computer, for the agent to search.
server:<id>, an MCP server you added.
For the Coding agent also commands, egress, browser, devhost and port:<name> (below).

The agent cannot change its own roster. No tool it has switches an entry on or off. Only you can, in the app or the CLI.

A switch applies at the next turn¶

You can switch an entry while the agent runs. In the app, use the switch beside the entry. In the CLI:

agentry agent grant assistant share off
agentry agent grant assistant knowledge:my-notes on

A change is pending until the agent's next turn. Then Agentry ends the segment, starts the next one with the change, continues the conversation and sends your message there. The chat says "Applying your change…". The agent is told which entries were switched off and on, by name. If the next segment cannot start, the agent stops and says why. A stopped agent takes the change when it next starts.

The first time something is given to an agent on this computer, Agentry asks you to agree to the entry's sentence.

At the first start. Agentry lists every entry that is on and not yet agreed to. The app asks in a dialog. In the CLI, agentry agent start asks at the terminal, and --yes agrees without asking. With no terminal and no --yes, the start is refused.
When a change widens the roster. Switching on an entry you have not agreed to, adding a pack or a server, or choosing another share folder asks again, in a dialog or at the terminal. A refusal changes nothing.
Turning an entry off and on again as its sentence still reads asks nothing.
Every start checks. A start, including the next segment of a switch, refuses a roster with an entry that is on and not agreed to.

Agreements are kept for each agent on this computer.

Knowledge packs, MCP servers, name and personality¶

Give an agent a pack kept on this computer in its Configuration (Knowledge packs) or with agentry agent configure <name> --knowledge <pack>; --no-knowledge takes it away. Add an MCP server in Configuration (an npm package, a PyPI package or a remote server at an https address, with an exact version for a package), or from a file in a QuickAgent manifest's server shape:

agentry agent configure assistant --add-server server.yaml
agentry agent configure assistant --remove-server server:<id>

Agentry asks the registry about a package server's version first. A version with a high or critical advisory is refused, unless you pass --allow-vulnerable-mcp. A package installs when the agent starts, so the first start after adding one waits for the install. An added server's container sees only its own store, never the share folder. A server that signs in by OAuth is listed as Needs a sign-in and cannot be switched on yet.

A name and a personality are not grants. They reach the agent, quoted, at the start of its next turn. Set them in Configuration (Save name and personality, at most 32 KiB), or:

agentry agent configure assistant --name Sandra --personality-file sandra.md

The sidebar shows an enabled agent by the name you gave it.

Using them in Agentry Desktop¶

Settings → Persistent Agents lists each agent with its state, its share folder and these buttons:

Enabled, a switch. An agent must be enabled to start.
Start and Stop. A stopped agent keeps its conversation and files.
Open, which opens the agent's page.
Configure, which opens its Configuration: Run when Agentry starts, its name and personality, its share folder, knowledge packs, MCP servers and the roster. The Coding agent's also has Dev server and Ports. Each change is saved as you make it, and a running agent takes it at its next turn.
Reset (below).

An enabled agent has an entry in the sidebar, with a dot for running. Its page is a chat in the style of a terminal. Enter sends, Shift+Enter starts a new line, and the last 500 lines of the transcript are reloaded. Usage beside the chat shows the segment's turns and tokens and the agent's lifetime totals, with not reported or unknown where the model's harness gives nothing. An ordinary run, a chat or a build goes on beside a running agent.

Using them with the CLI¶

agentry agent enable assistant          # an agent must be enabled to start
agentry agent start assistant           # runs in the background, returns when it is up
agentry agent chat assistant            # talk to it in this terminal
agentry agent stop assistant            # keeps its conversation and files

Command	Does
`list`	Lists the agents with their state (`running`, `stopped`, `disabled` or `desktop only`), when they started and their segment.
`show <name>`	Shows an agent's state, segment, usage, share folder, roster and folder. `--transcript N` adds the last N lines of its transcript.
`enable <name>`, `disable <name>`	Turns the agent on or off. Disabling keeps the conversation and files, and needs the agent stopped.
`start <name>`	Starts the agent in the background and prints its log while it comes up. `--yes` agrees to what it is given for the first time.
`stop <name>`	Ends the segment and prints the segment's envelope file.
`chat <name>`	Attaches this terminal to the running agent, after the last 500 lines of the transcript. Leaving the chat leaves the agent running.
`attach <name> --json`	Drives a running agent from a program (below).
`grant <name> <entry> on\\|off`	Switches a roster entry.
`configure <name>`	Changes the agent's name, personality, share folder, servers and packs, and for the Coding agent its dev server and ports.
`reset <name>`	Wipes the conversation and the agent's own files.

list, show, start, stop, grant and configure take --json.

Driving an agent from a program¶

agentry agent attach <name> --json is chat for a program. It speaks the session protocol of agentry run --session-protocol (Driving a session from a program): one JSON command a line on stdin, and the agent's events as JSON lines on descriptor 3. It needs CLI v0.6.157 or later.

{"send":{"text":"Add a note to data/notes.md about today's meeting"}}
{"end":{"finish":false}}

A send while another chat's turn is in flight is refused as busy.
An end, or the end of input, detaches. The agent keeps running.
A persistent agent takes no files through its chat. Put them in its share folder.
Descriptor 3 does not exist on Windows, so attach is refused there.

Running in the background¶

While the Assistant or the Coding agent is enabled, closing the Agentry Desktop window hides it instead of quitting. The agents keep running. The first time the window hides, Agentry says that it is still running and where its icon is: the system tray, the menu bar on macOS, or the notification area on Windows. Windows puts a new icon among the hidden icons (the ^ beside the clock). Drag it onto the taskbar to keep it in view.

With neither agent enabled, closing the window quits as before. Agentry Helper lives in the window, so it stops when the window hides.

The icon's menu has Open Agentry (a left click on the icon does the same), an item for each running agent that opens its page, and Quit. Quit is the way out. It stops every agent: each segment ends with its receipts, and the volumes and share folders are kept. A run in progress still asks you first. Cmd-Q and the Dock's Quit on macOS do the same. If your session ends without a quit (a sign-out on Windows), the next launch clears up the segment that was left and continues the conversation.

Opening Agentry Desktop a second time shows the window that is already running. Background running needs Agentry Desktop 0.6.148 or later.

Run when Agentry starts¶

Run when Agentry starts is a switch in each agent's Configuration (in the CLI, agentry agent configure <name> --run-on-start true). The app starts each such agent when it launches, and its conversation continues. An agent whose roster has an entry you have not agreed to on this computer waits for you and says so in the log, because no dialog belongs at a launch you did not open.

Start Agentry when you sign in, in Settings → Persistent Agents, adds a login item that launches this copy of Agentry Desktop with its window hidden. The agents set to run when Agentry starts then start in the background. If nothing runs in the background, the window is shown anyway.

The login item is an autostart entry on Linux, a LaunchAgent on macOS and a value in your Run key on Windows. The switch reads On only for the copy of the app the entry launches. The Windows uninstaller always removes the entry. Its option Also remove my settings removes the agents' share folders too, and says so.

What the Coding agent may reach¶

The Coding agent builds and runs software, reaches the internet and reads your share folder as it is. That is riskier than the other agents. Enabling it in Settings → Persistent Agents shows a warning, and turning it on asks in a dialog. Answer No and it stays off; the page says "Nothing was changed." While its segment runs, the sidebar says Coding agent running.

Its roster has three entries that are on by default and agreed to at its first start, and an entry for the dev server and each port you add. You can switch each off.

Programs (commands). Runs any program it chooses in its toolchain image (build tools, Git, curl, Python 3, Go, Node and npm), in its folders, as you: it builds and runs software, which is riskier than an agent that only reads and writes. There is no list of allowed programs. A program runs as you, in a folder inside the agent's own folders, and can write only there and in a temporary folder. A call ends after 10 minutes, and its output is capped. Agentry builds the toolchain image on your computer at the first start.
Open egress (egress). Reaches any address from its tools and the programs it runs (open egress): the internet, and also your local network and this computer's own services. The model itself is reached only through the runner's model proxy, as for every run. A knowledge pack that is on can be read by the programs the agent runs, and sent on with open egress on.
Browser (browser). Drives a headless browser to any public website, through the runner's browse proxy.
Dev server (devhost) and ports (port:<name>), when you add them. See below.

A dev server¶

The Coding agent can deploy to one server over SSH. In the app, Configure → Dev server takes user@host or user@host:port, then Choose a key file… (with its passphrase, if it has one) or a password. Check and save reaches the server and checks its host key. A key you have not accepted is shown to you to accept. The sign-in is saved in your system keychain, a key as the path of its file, and the host key is pinned. Then the app saves the server and asks you to agree to its sentence: Reaches your dev server … over SSH through the host link, as that account, with the sign-in saved in your keychain; its host key … is pinned. Check and save does not sign in, so a wrong password shows at the agent's first call to the server.

With the CLI:

agentry agent configure coder --dev-host deploy@devbox.lan --dev-key ~/.ssh/id_ed25519
agentry agent configure coder --no-dev-host

--dev-password and --dev-passphrase each name an environment variable that holds the value. A flag never takes the secret itself. With none, the CLI asks at the terminal. --no-dev-host removes the server and your agreement for it, but leaves its sign-in in your keychain.

Each segment reaches the server through the host link as a target host, so host keys work as they do there: a segment that finds another key refuses. A computer with no system keychain cannot keep the sign-in.

Ports¶

A port publishes something the Coding agent serves inside its sandbox, such as a dev server it started, on this computer, at http://127.0.0.1:<port> and the same number, so your browser can reach it. In the app, Configure → Ports takes a name (1 to 32 lower-case letters, digits and hyphens, such as web) and a number from 1024 to 65535. Add port asks in a dialog that names the address. A running agent's roster then shows Open in browser beside the port. In the CLI:

agentry agent configure coder --port web=3000
agentry agent configure coder --no-port web

You can add at most 8 ports. Only you can add one: the agent cannot publish a port itself.
A port is a roster entry with a sentence that says it publishes what the agent serves, where your browser and any program on this computer can reach it. It is on when you add it. Switch it with the switch in the app or agentry agent grant coder port:web off, and it closes at the next turn.
A port is published only while the Coding agent runs and its Programs entry is on, on this computer's loopback address (127.0.0.1, and ::1 where the computer has one).
A port another program on your computer already holds is not published. The segment's receipts/port-relay.log says which ports were published and which were refused.

Ports need CLI v0.6.157 or later and Agentry Desktop 0.6.149 or later.

Background programs¶

A program the Coding agent starts in the background, such as a dev server, keeps running between its calls. It has no time limit, and the agent reads the last 64 KiB of its output. At most four run at once. The agent can read a background program's output and stop it.

A background program ends when the agent's segment ends: at a stop and at the restart that applies a roster change. The agent is told at its next turn that its background programs ended, so it starts the server again instead of assuming it still runs.

From your own agent¶

The MCP server gives a host the tools agentry_agent_list, agentry_agent_show, agentry_agent_start, agentry_agent_stop, agentry_agent_send and agentry_agent_grant. A start that needs your agreement, and every roster switch, are two calls, like an install. Enabling, configuring and resetting an agent stay in the app or a terminal. These tools need the MCP server 0.6.19 or later.

Where the record is¶

Each agent has a folder under the runner home, ~/.agentry/runner/persistent/<name>/:

transcript.ndjson is the conversation: the turns, the tool calls, errors, permissions denied, files added and each segment's end. A line marks each segment's start and says whether it continued the conversation. Streamed chunks are left out. agentry agent show <name> --transcript N prints its end.
segments/<run>/ holds one segment's receipts and result envelope. The receipts record what the agent had in that segment, its roster included. receipts/share-checks.ndjson has a line for each file the malware check looked at.
usage.json adds up the segments' usage, and supervisor.log is the log of the process that runs the agent.
config.yaml keeps whether the agent is enabled, whether it runs when Agentry starts, its name and personality, its share folder, and its switches, ports and agreements. The dev server's sign-in is never in it.

Resetting an agent¶

Reset wipes the agent's conversation and its own files, and puts it back to its defaults: its name and personality, the servers and packs you gave it, its switches, your agreements, its share folder's location, its ports and dev server, and Run when Agentry starts. Its next start begins a new conversation and asks for your agreement again. The files in its share folder are kept, and so are the receipts of what it did. The agent must be stopped. (Before CLI v0.6.158 and the Agentry Desktop built on it, Reset keeps those choices and wipes only the conversation and the agent's own files.)

In the app, Reset in Settings → Persistent Agents asks on the page, then in a dialog. In the CLI, reset asks you to type the agent's name, or takes --confirm <name> when there is no terminal:

agentry agent reset assistant --confirm assistant

Disabling an agent, stopping it and quitting Agentry all keep the conversation and the files.