The desktop app: Home and Library¶

Agentry Desktop opens on Home, the first item in its sidebar. Home is a page of cards about what is yours: your recent runs, what is installed on this computer, your account and how your runs are set up. The QuickAgents on this computer are in Library, the second item.

Home came in Agentry Desktop 0.6.62. Library replaced the Installed item in 0.6.61, with Browse beneath it. The run history came in 0.6.63, pins in 0.6.65 and Settings → Home in 0.6.66. Publisher, the QuickAgents you publish with the actions to manage them, came in 0.6.76 (below), and Fork in 0.6.78 (below). The Deliverables folder, Home's Deliverables card and the files a run was for, listed first on its result, came in 0.6.136 (below). How the app finds the container engine your runs use is below.

Home¶

Home starts nothing. Opening it never starts a run, an install, an update check or anything that spends credits. Each card shows what it reads, and pressing a card opens the page where you act on it. A card that cannot read what it shows says so, and the other cards are still shown.

The cards, in their first order:

Deliverables. The newest files your runs were for, across the runs this computer remembers, with Open, View and Show in folder on each and Open Deliverables folder below them (Deliverables). It lists a file only when the run's own record names it and the file is still what the run recorded. It reads the run history and each run's record, never your Documents folder, so a file you put there yourself is not listed. It opens Settings → Run defaults at Deliverables.
Recent runs. Your last five runs, chats and built-in jobs (a draft by the Drafter, a review, a knowledge or voice build), newest first. Each row says what ran, where (on this computer or In Agentry), when, and how it ended, and opens that run's page. Signed in, it includes your runs In Agentry. Signed out, it lists this computer's runs and says that signing in adds the others. The card opens Settings → Run defaults at Recent runs (below).
Installed QuickAgents. How many QuickAgents are on this computer, how many have an update (from the check the app makes when it starts), and the five newest. A name opens its page. One installed from a folder has no registry page, so its name opens the Library. The card opens the Library.
Profile. Your name, handle, registry, plan and credits, with Top up credits where your plan offers it. It opens Settings → Profile. Signed out, it is a Sign in card instead.
Run defaults. Where runs go, their time and turn limits, the output folder, and Unsafe Mode while it is on (Unsafe Mode). It opens Settings → Run defaults. Nothing on the card can be changed from Home.

Agentry Desktop 0.6.136 added the Deliverables card. A Home you had arranged before then gets it once, at the end, after every card you already had, and no card moves. A new Home, and one you reset, has it first.

After them come your Pinned cards, if you have pinned anything, and the Scheduled card, if you pinned it from the Scheduled page: this month's calendar of your schedules and the next three runs (Scheduled runs). Pinning it puts it at the end of Home, and anything pinned later comes after it. Home settings, at the top right, opens Settings → Home.

Pins¶

You can put a QuickAgent you have installed on this computer on Home. Use Pin to Home on its row in the Library or on its page. Unpin from Home takes it off again.

Four to a card, 16 in all. Pins go on Pinned cards, four to a card, and Home holds at most four Pinned cards. A new pin goes in the first card with room, and a new card is added only when every card is full. Unpinning leaves the other pins in their cards, and a card with no pins left goes from Home. Once Home holds 16, Pin to Home is unavailable and says why.
Each pin shows the QuickAgent's name, its installed version, an update when one is out, and how its latest run went, or "Not run yet". Its latest run is its newest run or chat, on this computer or In Agentry.
Open latest run opens that run's page.
Run opens the usual run setup, so you choose the task, the files and where to run it. Nothing starts until you click that setup's own Run.
A pin stays on this computer. Pinning writes only the app's settings file on this computer. It tells the registry nothing, and it is not a star.
Only a QuickAgent installed on this computer can be pinned. Uninstalling it, or Forget, in the app takes its pin off Home once no other install of it is left (an install from a folder and one from a registry are counted apart). If the agentry command removes it instead, the pin stays and says the QuickAgent is no longer installed on this computer, with Unpin.

Settings → Home¶

Settings has a Home card. Its status line says how many cards Home shows and how many QuickAgents are pinned, such as "All 5 cards shown, 2 QuickAgents pinned." Its page has three parts:

Cards. One switch for each card above. A card you turn off is hidden from Home. It keeps its place, and turning it back on shows it there again. When every card is off and nothing is pinned, Home says so and links back here. A pinned Scheduled card is listed after the five, with its own switch.
Pinned. Every pin, card by card, with where it was installed from, its version, and Unpin. This Unpin works the same way as the one on Home and in the Library.
Reset Home… shows the five cards again in their first order and removes every pin, the Scheduled card included. It asks first, and says how many pins will go. Nothing is uninstalled, and Pin to Home puts a QuickAgent back.

You cannot reorder the cards or change their size yet. A Home arranged by a newer Agentry Desktop is kept as it is: this one shows the five cards, holds the switches, and offers Reset Home to start again from the defaults.

The run history¶

So that Recent runs and each pin can show runs after the app restarts, Agentry Desktop keeps a short history of the runs on this computer. It keeps the last 50, including the built-in agents' jobs.

What it keeps. For each run: which QuickAgent ran (or which built-in job), on which registry, when it started and ended, how it ended, and the folder its output went to.
What it never keeps. The task you gave, your inputs, the result, the log, or any secret. None of them is written to the history. What a run writes stays in its own output folder.
Runs In Agentry are not written to the history. Home reads them from the registry while you are signed in. A run In Agentry is written to it only when its output comes down to this computer.
A run's page shows how it ended (from the history) and its result (from its output folder). If the folder has gone, the page says so and offers Remove from Recent runs. For a finished run In Agentry whose output is not on this computer, the page offers Download output while the registry still holds it (30 days). Downloading spends no credits.

To change it, open Settings → Run defaults → Recent runs:

Remember recent runs is on unless you turn it off. Turning it off forgets every run in the history and keeps nothing from then on.
Clear run history forgets the runs kept so far and keeps remembering new ones.

Neither one deletes a run's output folder. The history is a file in the app's settings folder, runs.yaml, beside desktop.yaml. Only you can read it.

Deliverables¶

A run writes many files, and you came for one or two of them. Those are its deliverables: the report, the document or the table the run was for. The run's output folder still holds everything it wrote, as the record of the run. Agentry Desktop 0.6.136 copies the deliverables to a folder where you keep your work, lists them first on the run's result, and gives Home a card for them. The same idea works from the command line and in other clients: see Deliverables.

The Deliverables folder¶

Settings → Run defaults → Deliverables has a switch, Copy each run's deliverables to a folder, and the folder itself.

On unless you turn it off. Every QuickAgent run and chat on this computer starts with the folder, and a run In Agentry is copied when its output comes down. It applies from the next run, and nothing already run is copied afterwards.
The folder is an Agentry folder inside your Documents folder until you choose another: Windows' own Documents folder (the one Windows reports, which follows a folder you moved to another drive or into OneDrive), the one your Linux desktop names (XDG_DOCUMENTS_DIR, else ~/Documents), and ~/Documents on macOS. Choose… opens your system's folder dialog, and the dialog is the only way to set it: nothing a run or a page says can name the folder. Use the default goes back.
What lands there. For each run, a folder named for the QuickAgent and the time, such as weekly-digest/2026-10-17 0930 Weekly digest/, holding a copy of each deliverable. The name is the file's title when the run has one deliverable, and the run's id when it has several. A name is made plain for every system, and a file that is already there is never replaced: the new one is name (2).md.
Copies, never moves. The run's own folder keeps everything and is not changed; its receipts folder gains a note of what was copied. The app never deletes a copy.
A mark on each copy. On Windows and macOS a copy is marked as a download, so the system treats it the way it treats a file from the internet: Windows adds the Mark-of-the-Web, which Office reads as a file from outside, and macOS adds its quarantine flag. Linux has no such mark.
Not a Documents scan. The app lists what a run recorded, and it does not look through the folder.

Your own agentry command does not use this setting: agentry run copies nothing unless you give it --deliver-to or deliver.folder (Running them). A run a schedule fires is listed in the app, but it is copied only when the command's deliver.folder is set.

On a run's result¶

When a run has deliverables, they are the first thing on its result, above the final message, whether you opened the result when the run ended or from Recent runs. Each shows its title and file name, its type and size, where its copy is, and three buttons:

Open opens the file in the program your computer has for its type.
View shows it in the app: a PDF in the app's own viewer, Markdown rendered as formatted text, and plain text, CSV and JSON as text. A document made by another program, such as a spreadsheet, has no View.
Show in folder shows the file in your file manager, in the Deliverables folder when it was copied there and in the run's folder otherwise. It opens nothing.

Open takes only these types: PDF, Markdown, text, CSV, JSON, PNG, JPEG, Word (.docx), Excel (.xlsx) and PowerPoint (.pptx). Each is checked by its first bytes as well as its name, so a file called report.pdf that is not a PDF is not opened. An Office file is also refused if it carries a macro project, a control or an embedded object. Any other type, such as a web page, a shortcut, a script or a document with macros, has no Open: its row says why, and Show in folder finds it so you can decide for yourself.

What Open hands to your computer is not the file the run wrote. It is the copy in your Deliverables folder when that copy still holds exactly the run's bytes, so what you edit stays where you keep your work. Otherwise it is a fresh copy made for the click, with the same download mark, in a folder the app removes when it quits. If you changed your copy, Open gives you the run's original in a fresh copy and leaves yours alone.

A file is listed only if it is still the file the run recorded. The app checks its contents against the record each time. A file that has changed, or gone, or that the record names outside the run's reports folder, is not shown, and the section says how many were left out.

On Home¶

The Deliverables card lists the five newest files across your runs, with the same three buttons and the run each came from. Open Deliverables folder shows the folder itself. The card says what is missing when it lists nothing: no run yet, the switch off, or Remember recent runs off, which leaves the card nothing to read (the run history).

Runs In Agentry¶

A run In Agentry that you follow in the app is copied when its output comes down. One that ended while the app was closed is copied when you open its page and use Download output, or open it again after. A run In Agentry lists deliverables only when the runner that ran it recorded them.

Library¶

Library lists the QuickAgents installed on this computer. Browse, the item beneath it, searches the registry for more. Browse is shown in the sidebar while you are in Library or Browse.

Search your QuickAgents filters the list as you type. Its button, or Enter, searches the registry for the same words in Browse.
A row installed from a registry offers Details (its page), Update when one is out, Pin to Home and Uninstall. A row installed from a folder offers Run in place of Details. Check for updates asks the registry about every QuickAgent this app manages.
Below the list, the Library shows two more groups: Recorded by the CLI, QuickAgents the agentry command recorded that this app does not manage, and No longer on disk, records whose folder has gone, which offer Forget.
A QuickAgent's page shows ← back to Library, ← back to Browse or ← back to Home, depending on where you opened it from.

The Library is the record on this computer, the same one the agentry command reads and writes (installed.yaml). It is not your account's Installed QuickAgents on the website, which lists the releases you accepted for your account (Installed to your account). The two are never synced: installing in the app does not add to your account, and installing to your account does not put anything on this computer.

Publisher¶

Publisher is in the sidebar while you are signed in. It is the desktop's copy of the website's Publisher list. It lists the QuickAgents in your namespace and in each organization you are a member of. Pick the namespace at the top when you have more than one.

Find a QuickAgent as on the website: search by name and summary, filter by visibility, state (active or retired) and forks, and sort by newest, most installed over 30 days, last submission or name.
Each row shows the QuickAgent's badges: Private, Fork, Retired, Quarantined. A fork's row also says Fork of and the QuickAgent it came from.
The actions on a row are Edit, Make private or Make public, Retire or Restore, and Delete. They do what they do on the website (Managing your QuickAgents):
a retired QuickAgent offers only Restore and Delete;
a fork never offers Make public;
in an organization, only its admins see the actions that change who can see a QuickAgent, or retire or delete it.
The app asks before every action in a dialog of your system's own, and the registry decides. If it refuses, the app says why, in the website's words.
Delete asks you to type the QuickAgent's name first.
A QuickAgent with no version is deleted outright, and its name is free again.
One with versions has every version withdrawn, and its name stays held for good.

The actions need a sign-in made with Agentry Desktop 0.6.76 or later. A sign-in from an earlier version can list your QuickAgents but not change them, and Publisher says so. Sign out and sign in again under Settings to use them.

Fork¶

A QuickAgent's page offers Fork beside Install while you are signed in, on a public QuickAgent with a published version that is not quarantined, blocked or itself a fork. Forking does what it does on the website (Forking a QuickAgent):

Choose where the fork goes: your own namespace, or an organization where you are an admin or a member. The dialog says what a fork is: private for good, its first version a submission that costs credits, and what hosted runs of it pay the original's publisher.
The fork keeps the original's name. If that name is taken or held where you chose, the dialog says so and asks for another.
The app asks once more in a dialog of your system's own, then the registry makes the fork.

The app then opens Publisher on the fork and follows it: the copy of its history, then its first version through the pipeline, until it is published. Use Edit on its row to make and submit its next version.

A fork's page says Fork of the original and the version it came from, and opens the original's page while it can still be read. A public QuickAgent's page shows how many forks it has, as a number only.

The container engine¶

QuickAgents that run on this computer run in containers, so the app needs a container engine that serves the Docker API. The Container engine card, under Settings → Run defaults and in the first-run setup, shows the engine the app found by kind and version, such as "podman 5.8.4, rootless", or what is missing and the one step that fixes it. Since Agentry Desktop 0.6.122 the app works with any engine in the runner's list, not only Docker.

How it finds one. It asks in a fixed order, and an engine counts only when it answers, never because a socket file exists. First comes your docker command's own setting (DOCKER_HOST, DOCKER_CONTEXT or docker context use). Next come the engines that run in a virtual machine, at their usual sockets: Docker Desktop, Colima, OrbStack, Rancher Desktop, Lima and a podman machine. Last comes podman on this computer. The first that answers is the one your runs use, until you press Re-detect, which searches again, or choose one yourself (next). Use Re-detect after you change engines. It is unavailable while a run is in progress.
Your choice of engine. Choose an engine… on the Container engine card (Agentry Desktop 0.6.133 or later) lists every engine that answers on this computer, each once: Agentry's engine where it is installed, each of your docker command's contexts, each engine at its usual socket, and podman on this computer. Use this picks one, and the app remembers it: from then on it asks that engine alone, when it opens and on Re-detect. If your chosen engine stops answering, the card says so, and the app does not fall back to another engine. Use automatic goes back to the fixed order. A docker context that points at another machine (tcp:// or ssh://) is not offered, because a run needs an engine on this computer; Where the app looked says why. When the app was started with its engine named in its environment (DOCKER_HOST, DOCKER_CONTEXT or AGENTRY_ENGINE), it drives that engine and the picker says so.
On Linux. If podman is installed and its API socket is off, one click turns the socket on for you, with no password and no restart. If no engine is installed, the app offers your distribution's own: podman on Fedora and the RHEL family, and Docker Engine on Debian, Ubuntu, Arch and SUSE. Your system asks for your password to install it. Docker Engine also needs you in the docker group and a restart, and the card takes you through both.
On macOS. With no engine, Install Agentry's engine (Agentry Desktop 0.6.124 or later) sets one up for you. It runs a Docker Engine in a small Linux virtual machine, using Colima, Lima and the docker CLI, each downloaded from its publisher and checked against a SHA-256 pinned in the app. They live under ~/Library/Application Support/agentry-desktop/engine/, with no Homebrew and no administrator password, and your own docker settings are left as they are. The first start downloads the virtual machine's image and takes a few minutes; later starts take about twenty seconds. The app starts it when it opens and stops it when it quits. Remove deletes it with its data. You can instead install Docker Desktop, Colima, Rancher Desktop (its dockerd engine) or Podman Desktop yourself, and the app finds whichever answers.
On Windows. With no engine, Install Rancher Desktop (Agentry Desktop 0.6.132 or later, on x86-64) sets one up for you: Rancher Desktop, SUSE's application, with its dockerd (moby) engine and Kubernetes off. The app downloads its installer from its GitHub release, checks it against the SHA-512 the release publishes, and installs it for your account alone, with no administrator password. It needs Windows Subsystem for Linux: where that is not on yet, the button reads Install WSL, then Rancher Desktop, Windows asks for administrator consent once to install it, and after a restart you click again to finish. The first start takes a few minutes. Rancher Desktop is then your own application, listed in Windows' installed apps with its own updater and uninstaller. The app starts it when it opens and never removes it, and Start quits Rancher Desktop first if it is running, then starts it again, which brings back an engine that has stopped answering. You can instead install Docker Desktop, or Rancher Desktop with its dockerd (moby) engine, yourself, and the app finds either; or run the agentry command inside WSL 2 against a Docker Engine there.
Docker Desktop's licence. Docker Desktop is free for personal use and small companies and licensed per seat for others; see Docker's terms.
Two things the card warns about. One is a credential helper that your ~/.docker/config.json names and this computer does not have, such as the desktop entry Docker Desktop leaves behind after it is removed: every image download fails until the entry is removed or the helper installed. The other is a socket file with nothing answering behind it, which an engine leaves when it stops. Start that engine, or remove the file. When nothing answers, Where the app looked lists every place it tried.