agentry

command
v0.7.41-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 139 Imported by: 0

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 messenger: the messengers a persistent agent is reached on, each an account the person makes on the service and pairs with their 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 providers add openai --sign-in` 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 providers add anthropic --sign-in`, 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 providers add openrouter|poe|huggingface --connect` 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 providers 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).

Saved models and providers: `agentry models` and `agentry providers`. A provider is a credential (a key, a model sign-in, a connected account or Agentry credits, and for an endpoint of your own its address); a saved model is a provider plus a model id, under a name you give it. Up to ten are kept on a computer, and the default is what a run uses unless it names another. Every save is checked first (pkg/runner/modelcheck), and a model or provider something still names is not removed until it is moved.

Model sign-ins: a person's own grant that lets their local runs spend a model vendor's plan. `agentry providers` lists, adds and removes them, apart from `agentry connections` (MCP servers' grants), and the deprecated `agentry model-signins` still does under its own name. 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.

How the CLI explains itself: the root help's purpose line, docs link and command groups, with the credential prose after the command list, and one path for every usage error (a flag the command does not take, the wrong number of arguments, a command that does not exist), which prints the error, a pointer to the command's help, and exits with the usage code.

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL