agentry

command
v0.7.14-dev.7 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 129 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 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

Jump to

Keyboard shortcuts

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