Documentation
¶
Overview ¶
The advisories on a QuickAgent this machine holds: asked of the registry with the archive digest of the release laid down here, which proves the holding, so a QuickAgent that has since gone private, been retired or been deleted still answers its advisories, signed in or not.
Capability-summary rendering (install-time display): the declared security contract is shown before anything is written to disk, and network egress (the release's own or a package MCP server's), exec, a remote MCP server or a target host requires confirmation.
API client plumbing: bearer-authenticated apiclient construction, RFC 9457 problem rendering, and the download/verify helpers shared by install and verify.
`agentry acp`: one QuickAgent run for an editor or an orchestrating agent that speaks the Agent Client Protocol, with this process as the agent side (pkg/runner/acpagent) and the same run underneath as `agentry run`.
agentry agent: the persistent agents, built-in QuickAgents the runner keeps between conversations (pkg/runner/persistent).
The Coding agent's git host accounts, set up by agentry agent configure: whose account it is, its user name and commit identity, and its token, read without echo and kept in the system keychain (pkg/runner/persistent).
agentry agent compact: an upkeep turn now, then a new conversation that opens with the agent's handoff (pkg/runner/persistent).
agentry agent memory: a persistent agent's memory, the wiki it keeps on a volume of its own (pkg/runner/persistent).
agentry agent grant and configure: a persistent agent's roster, the share folder, the servers and packs the person adds, its name and personality (pkg/runner/persistent).
agentry agent secret: the secrets the person stores for a persistent agent, each kept in the system keychain and given, while it is on, to the servers that declare it and to the Coding agent's programs (pkg/runner/persistent).
agentry agent skill: the skills a persistent agent reads, built in and the person's own, added from a folder or a zip on this computer and checked as the share is (pkg/runner/persistent, pkg/runner/skill).
agentry agent tasks: the tasks the Assistant registered for its heartbeat to fire, and the person's pause, resume and remove (pkg/runner/persistent).
`agentry browser ensure`: pull the browser image this CLI pins ahead of any run. A sandbox host runs it from the runhost image as it is set up and at each release roll, as it runs `files ensure`, so no hosted run of a QuickAgent that declares capabilities.browser downloads Chromium inside a paid run.
`agentry builtins`: the packages this binary embeds and runs as builtin — the Knowledge Creator, the Drafter, and any added to localrun.Builtins() — each with the digest of its release archive. The registry holds every one of them as these same bytes, so a person reads a built-in's instruction in the directory and checks it against their own binary with the digest printed here.
`agentry builtins publish` is what the CLI's tag release runs to put them there. Only the registry's owner can: the built-ins live in their organization's namespace, and the registry refuses a publish to it from any account without that right, so an ordinary user cannot publish a built-in on a registry they do not own.
Sign in with ChatGPT: `agentry model-signins add chatgpt` and the offer in `agentry setup`. The flow is mcpauth.ChatGPT, the store modelsignin.SignInChatGPT; this is the terminal around them.
Use your Claude subscription (runs Claude Code): `agentry model-signins add claude`, its removal, and the offer in `agentry setup`. The sign-in and its removal are pkg/runner/claudesignin, which the desktop calls too; this is the terminal around them.
Connect your account: `agentry model-signins add openrouter|poe|huggingface` and the offer in `agentry setup`. The flows are mcpauth's OpenRouter, Poe and HuggingFace; the store is modelsignin.KeepConnected, which keeps the key in the model key's keychain entry; this is the terminal around them. The key is never printed, logged or written outside the keychain.
Connections: a person's OAuth grant to a remote MCP server, or at a package server's issuer, for one QuickAgent release. A run asks for each one it lacks at Start, on a terminal, and refreshes each before the sandbox starts; `agentry connect` makes them ahead of a run; `agentry connections` lists and removes them and keeps the person's own OAuth clients. The run is given an access token and nothing else.
Sign in with GitHub for a Copilot plan: `agentry model-signins add copilot` and the offer in `agentry setup`. The flow is mcpauth.GitHub, the store modelsignin.SignInCopilot; this is the terminal around them.
`agentry doctor`: the "check my setup" verb the converted agents lost with their doctor.sh. `setup` prepares a machine; `doctor` reports, without changing anything, whether a scheduled `agentry run` would get past its preflight — policy and model, the container engine and the pinned images, the registry, and for a specific ref the verified install, its MCP server store, its profile and every declared secret (the exit-11 refusal, predicted instead of met at 03:00).
`agentry files ensure`: pull the files image this CLI pins, and refresh the ClamAV signatures, ahead of any run. A sandbox host runs it from the runhost image at each update, so the first hosted run with inputs downloads neither the decoders nor the signatures inside a paid run. It is the decode step's own pull and refresh, alone.
`agentry fork`: fork a public QuickAgent into the signed-in account's namespace, or an organization it publishes for, over the core's POST /agents/{ns}/{name}/fork. The core decides every rule: the origin public, not quarantined or blocked and with a published version; the caller able to create in the target; the name free; the quota and the private-agent cap. The fork's first version is a submission through the pipeline, charged like any. Fork needs agent:publish, which the sign-in grant carries.
What a fork is, and every refusal, are said in the site's words, as the desktop says them (services_fork.go).
`agentry info` and `agentry search` (discovery). search calls the real full-text endpoint (GET /search) with its facet filters; info shows one agent, its latest published version, its capability contract, and how to run it (cmd_info_run.go).
How to run a QuickAgent, as `agentry info` shows it: the latest release's intake questions and how to answer each, the files it takes, the keys it declares, its modes and its publisher's guide. A person reads it before `agentry run`; a host agent reads the same in --json before it answers the questions with --intake. Everything comes from the manifest the resolve already returned. What the publisher wrote is cut to a bound and, on a terminal, cleaned and set behind termtext's gutter, so it can neither rewrite the terminal nor pass for the CLI's own lines.
`agentry init`: scaffold a new agent workspace with a per-kind agent.yaml matching the manifest schema, README.md, a LICENSE placeholder, and the kind's entrypoint file. --from imports an existing SKILL.md or MCP server.json instead (cmd_init_from.go).
`agentry init --from`: import wizards that seed a QuickAgent workspace from something that already exists — an Agent Skills SKILL.md (with its sibling files) or an MCP registry server.json — and populate the manifest from what the source states. The capability contract is never guessed: what the source cannot state (egress, secrets, exec, filesystem) is asked on a terminal, with hints found in the source offered as defaults the author confirms, or taken from explicit --egress/--secrets/--exec/--fs-* answers; without either, the wizard refuses rather than writing a "pure text" contract nobody decided on.
`agentry install`: resolve → download → verify digest AND the DSSE attestation signature → show the declared capability contract, diffed against whatever this machine last installed → extract → lay the release down for one target: the runner home (the default), or one of the two coding-agent exports (claude-skill, agents-md).
`agentry list`: the shared install state as this machine holds it — every record `install` and `run` wrote, each with whether its directory still exists. Text for a person, --json for a client; nothing is changed. The runner's own consent records (target "runner") are listed as what they are.
`agentry login`: obtain a PAT — through the browser (the default on a terminal: the registry's authorize page mints a one-time code to a loopback listener and this process exchanges it) or pasted from stdin (`--paste`, and the default when stdin is not a terminal) — verify it against GET /user, store it (OS keychain first, config-file fallback for headless machines), and pin the registry's signing keys (TOFU).
Model sign-ins: a person's own grant that lets their local runs spend a model vendor's plan. `agentry model-signins` lists and removes them, apart from `agentry connections` (MCP servers' grants). A run whose plan spends one is handed the access token alone, refreshed now and before it expires; a hosted run never spends one.
`agentry profiles`: list and remove the MCP profiles guided setup created — the persistent keys/identities per QuickAgent signature. Secret VALUES are never printed by any subcommand.
`agentry publish`: submit a version and follow the pipeline to a verdict. --tag submits an existing repo tag (git-tag source); without it the CLI packs the deterministic archive locally and uploads it (cli-upload source). Progress arrives over the registry's event stream when it has one, else it is polled every 2s.
`agentry run`: resolve → verify → materialize → compile → enforce → run → receipt, one agent per invocation. First use of a digest IS the install: the verified workspace, the compiled plan, and the pulled/built images all persist under ~/.agentry/runner so later runs execute without re-deriving anything. The verify gate is the same one `agentry install` applies — a run is an install that also executes.
Declared-MCP-server wiring for `agentry run`: resolve the manifest pins (offline when the signature's store already holds matching resolutions — the recorded pin is the trust decision), install into the store as part of the run's install step, and widen the guided profile to the servers' secret names.
`agentry runner-tools` (hidden): serve the companion tools server on stdio, exactly as the runner image's `tools` mode does inside the tools container. It exists for two reasons: debugging a tool spec without a docker round-trip, and letting acceptance scripts exercise the MCP surface on machines with no engine.
`agentry schedule`: runs on this computer for later and on repeat. The store under the runner home is the truth about every schedule; the operating system's own scheduler only wakes `agentry schedule fire <id>`, which re-reads the store and decides. A fire runs the exact version consented to when the schedule was made, autonomous, never with a blanket --yes, and everything it needs is checked when the schedule is made.
`agentry schedule add --check`: everything add decides before it keeps a schedule, with nothing kept, asked or changed. Agentry Desktop's When step keeps Schedule disabled until it says ready, then makes the schedule with this binary, whose path the system's alarm pins.
`agentry schedule --signed-out`: a schedule that also runs while its person is signed out. Linux with Docker Engine only. Linger, turned on once behind a confirm, keeps the person's systemd user manager running after sign-out; the keys a fire reads are sealed into an encrypted systemd credential the unit loads, because the keychain is locked then.
`agentry setup`: prepare a machine for QuickAgent runs before any agent is involved — configure the operator's preferred LLM provider into the policy, then stand up the docker-mcp-gateway plane (pull pinned images, build the runner image) right away instead of lazily at first agent use. Idempotent; `agentry run` still self-heals, so setup is a convenience, not a gate.
`agentry uninstall` removes this machine's RUNNER state for a QuickAgent: the verified install cache (workspace + compiled plans) and, BY DEFAULT, its MCP profile — stored keys, identities, and the installed MCP-server store (remove on uninstall is the default; keeping credentials is the explicit choice). --keep-mcp retains the profile directory, which is signature-locked: only a reinstall of the exact same release digest can ever use it again — not another QuickAgent, not another user, not a newer version of this one.
The version's OAuth connections go with its profile: each is revoked at the vendor where it offers that, and the outcome is recorded; --keep-mcp keeps them, locked to the release they were made for, like the profile.
Embedded installs (claude-skill / agents-md exports, and the mcp exports of older clients) are separate state with their own records; this command does not touch them.
`agentry validate`: offline parity with the server's submit validation — the manifest rules via pkg/manifest, the S1 inventory subset via pkg/archive's sniffers, and the S3/S4 scan via pkg/rules, run over the files that publish would actually ship. The check itself is pkg/validate; the command adds the rule bundle's precedence and the --rules-update fetch.
`agentry verify`: download a pinned version, check its sha256 digest against the registry, and verify the DSSE attestation against the signing keys pinned for that registry.
`agentry yank`: author yank of a published version. Yanked versions leave range resolution but stay downloadable by exact pin; the version string is burned forever.
CLI configuration and credential storage: PATs live in the OS keychain via go-keyring, with a chmod-600 config-file fallback for headless machines; ~/.config/agentry/config.yaml records the default registry and per-registry token references.
How a command's failure reaches the person: one line on stderr that says what happened in the product's words and what to do, and beneath it, only with --verbose, the client library's own error. Two failures have raw forms a person cannot act on, a registry that cannot be reached and a container engine that does not answer; each is carried as an error that renders the line itself and keeps the raw text as its detail.
Which commands answer --json. The root flag is one for the whole tree; each command that honours it is marked here, the root flag's help lists them from the tree, and a test runs every marked command under --json and holds its stdout to one JSON object (login's NDJSON aside). A path named here that the tree does not have is a programming error, caught the first time the tree is built.
agentry is the developer CLI: init, validate, login, publish, install, verify, search, info, and yank against an Agentry registry.
Minimum-CLI-version enforcement (the CLI checks the registry's `meta` for its min-supported-version).
The "next steps" block the first-run commands end with. After a sign-in, a setup, an install into the runner home or a clean validate, the commands that follow are named, so a person is not left to find them in the docs. The block goes on stderr, beside the narration, and never under --json, whose stdout is the result and whose reader is a program.
How the CLI speaks beside its result: narration on stderr that --quiet silences, stage lines for long operations that show only on a terminal, and colour that is off under NO_COLOR, off the terminal and under --json. The result itself (stdout, or the JSON a --json asks for) is untouched by any of it.
`agentry validate --rules-update`: fetch the registry's current S3/S4 rule bundle and cache it, so local validation can track rules that move faster than CLI releases.
Trust model, stated plainly: the bundle is pinned by DIGEST. The registry advertises the digest recorded on its ruleset_releases row, the CLI recomputes that digest over what it received, and a mismatch is a hard refusal. That defeats a corrupted or truncated transfer and a proxy that rewrites bytes; on its own it does NOT defeat a registry that lies about both the bundle and its digest, which is what a signature buys. When the registry signs the bundle, the signature is verified against the pinned keys; a registry that does not sign is tolerated.
Cache layout: ~/.config/agentry/rules/<semver>/{bundle.yaml,*.yaml}, one directory per version, alongside the config (see installed.go for why everything the CLI keeps lives under one root).
Source Files
¶
- advisories.go
- builtin_budgets.go
- builtin_envelope.go
- caps.go
- client.go
- cmd_acp.go
- cmd_agent.go
- cmd_agent_account.go
- cmd_agent_calendar.go
- cmd_agent_compact.go
- cmd_agent_fastmail.go
- cmd_agent_google.go
- cmd_agent_helper.go
- cmd_agent_install.go
- cmd_agent_mail.go
- cmd_agent_memory.go
- cmd_agent_microsoft.go
- cmd_agent_roster.go
- cmd_agent_secret.go
- cmd_agent_skill.go
- cmd_agent_subagents.go
- cmd_agent_tasks.go
- cmd_browser.go
- cmd_builtins.go
- cmd_chatgpt.go
- cmd_claude.go
- cmd_connect.go
- cmd_connections.go
- cmd_copilot.go
- cmd_deliver.go
- cmd_destinations.go
- cmd_doctor.go
- cmd_draft.go
- cmd_draft_knowledge.go
- cmd_draft_revise.go
- cmd_files.go
- cmd_fork.go
- cmd_info.go
- cmd_info_run.go
- cmd_init.go
- cmd_init_from.go
- cmd_install.go
- cmd_install_local.go
- cmd_knowledge.go
- cmd_knowledge_ship.go
- cmd_knowledge_store.go
- cmd_list.go
- cmd_login.go
- cmd_login_machine.go
- cmd_logout.go
- cmd_modelsignins.go
- cmd_profiles.go
- cmd_publish.go
- cmd_publish_ship.go
- cmd_report_design.go
- cmd_review.go
- cmd_run.go
- cmd_run_knowledge.go
- cmd_run_mcp.go
- cmd_run_runhost.go
- cmd_run_runhost_carry.go
- cmd_run_runhost_follow.go
- cmd_run_runhost_session.go
- cmd_run_shipped.go
- cmd_runhost.go
- cmd_runhost_credits.go
- cmd_runhost_job.go
- cmd_runhost_live.go
- cmd_runhost_service.go
- cmd_runnertools.go
- cmd_runs.go
- cmd_schedule.go
- cmd_schedule_check.go
- cmd_schedule_signedout.go
- cmd_setup.go
- cmd_targethosts.go
- cmd_uninstall.go
- cmd_validate.go
- cmd_verify.go
- cmd_voice.go
- cmd_voice_account.go
- cmd_whoami.go
- cmd_yank.go
- config.go
- credits.go
- envtoken.go
- errors.go
- jsoncommands.go
- main.go
- minversion.go
- nextsteps.go
- openflags_unix.go
- output.go
- protocol_fd_unix.go
- publish_stream.go
- report_theme.go
- rulescache.go
- run_summary.go
- run_usage.go
- rungrant.go