microagent registry

Last updated: 2026-07-30

microagent registry login <registry> -u <user> [--password-stdin]   Store registry credentials
microagent registry logout <registry>                               Remove stored credentials
microagent registry list                                            List registries with stored credentials

registry ls is accepted as an alias for registry list.

microagent pulls and pushes OCI images by talking to registries directly — it does not depend on Docker, Docker Desktop, or any docker-credential-* helper. Public images always pull anonymously. For private registries, credentials are resolved from static credential files only; credential helpers are never executed.

Credential sources

Resolved in order, first match wins — all Docker-free:

1. $REGISTRY_AUTH_FILE — the vendor-neutral file convention shared with Podman, Skopeo, and Buildah ({"auths":{...}} JSON).
2. ~/.microagent/auth.json — microagent’s own credential file, written by microagent registry login (mode 0600).
3. anonymous — no credentials (public images).

Docker’s ~/.docker/config.json is never read, and credential helpers (credsStore/credHelpers) are never executed — microagent has no dependency on Docker or Docker Desktop.

Examples

Log in to GitHub Container Registry with a token piped on stdin (the password is never passed as an argument, so it cannot leak into the process table or shell history):

echo "$GHCR_TOKEN" | microagent registry login ghcr.io -u USERNAME --password-stdin

Log in interactively (the prompt reads the password without echo):

microagent registry login registry.example.com -u alice

List and remove stored credentials:

microagent registry list
microagent registry logout ghcr.io

Use a shared auth file instead of microagent’s own store:

export REGISTRY_AUTH_FILE=~/auth.json
microagent run registry.example.com/team/app

Flags

Flag	Command	Description
-u, --username	login	Registry username (required).
--password-stdin	login	Read the password from stdin instead of prompting.

Notes

• microagent registry login stores base64(username:password) — the standard encoding, the same one Docker/OCI config files use. This is encoding, not encryption; the file is written 0600. microagent is otherwise a secret conduit, not a store (see secret).
• microagent never writes Docker’s ~/.docker/config.json.

Exit status

All subcommands exit 0 on success and follow the shared exit codes on failure - 1 for an operation that ran and failed, 2 for a usage error.

Related

• rootfs - the build path that pulls with these credentials.
• run - one-shot boots pull private images the same way.
• secret - deliver secrets into the guest at runtime.