Agent role manual

Agent Service Architecture

flowchart TB
    subgraph loop [Agent Automation Loop]
        poll[Poll MPFS facts and Antithesis API runs]
        plan[Plan actions for pending and running test-runs]
        download[Download test assets from GitHub]
        validate[Local docker compose validation]
        push[Push config image and launch on Antithesis]
        accept[Report acceptance on-chain once the run is observed]
        reconcile[Match runs to on-chain test-runs by description]
        outcome[Derive outcome from terminal run status and failing properties]
        report[Report completion on-chain]
    end

    poll --> plan
    plan -->|pending from trusted requester| download --> validate --> push --> accept
    plan -->|running| reconcile --> outcome --> report

    MPFS[(MPFS)] <--> poll
    AT[Antithesis API] --> poll
    GH[GitHub] --> download
    AT2[Antithesis platform] <--> push
    MPFS <--> accept
    MPFS <--> report

On every poll cycle the agent reads both the on-chain test-run facts (from MPFS) and the runs visible in the Antithesis REST API. Pending test-runs from trusted requesters are launched (assets downloaded, validated with docker compose, pushed as a config image); the on-chain accepted fact is only submitted once the launched run becomes observable in the API. Running test-runs are matched to API runs by their rendered description; when a matched run reaches a terminal status, the agent derives the outcome (completed with a triage report and no failing test properties maps to success; incomplete and cancelled map to failure) and reports it on-chain.

Running as Docker Service

The agent can run as an automated Docker service that continuously polls for and processes test runs.

See the Deployment Guide for full setup instructions including secrets, docker-compose configuration, and startup. For production host paths, GAR config.json generation, secret rotation, and post-rotation checks, see the agent/oracle config and secrets runbook.

Automation flags

Flag	Description	Default
`--poll-interval`	Seconds between polling cycles	30
`--minutes`	Time window (in minutes) for the legacy email-collection commands	1440
`--trust-all-requesters`	Accept test runs from any requester (skip trusted list check)	disabled
`--trusted-test-requester`	GitHub username of a trusted requester (repeatable)	—

Deprecated flag

The --days flag was replaced by --minutes in v0.4.1.1. Use --minutes 1440 instead of --days 1.

Environment variables

Each of the variables below — except MOOG_SECRETS_FILE and DOCKER_CONFIG — has a matching YAML key in secrets.yaml and a matching CLI flag. The parser combines all three sources in the order CLI > env > YAML, so a value set on the command line wins over an env variable, which in turn wins over the YAML file. See Secrets management for the full key reference.

Variable	YAML key	Description
`MOOG_MPFS_HOST`	`mpfsHost`	URL of the MPFS service
`MOOG_WALLET_FILE`	`walletFile`	Path to the agent wallet JSON file
`MOOG_TOKEN_ID`	`tokenId`	The moog token asset ID
`MOOG_SECRETS_FILE`	—	Path to `secrets.yaml` (bootstrap; cannot itself live in the YAML)
`MOOG_WAIT`	`wait`	Number of MPFS poll cycles to wait for tx inclusion
`MOOG_MPFS_TIMEOUT_SECONDS`	`mpfsTimeoutSeconds`	Per-request MPFS HTTP timeout in seconds
`POLL_INTERVAL_SECONDS`	`pollIntervalSeconds`	Agent poll interval (alternative to `--poll-interval`)
`MOOG_ANTITHESIS_USER`	`antithesisUser`	Antithesis platform username
`MOOG_ANTITHESIS_LAUNCH_URL`	`antithesisLaunchUrl`	Antithesis tenant launch URL
`MOOG_REGISTRY`	`registry`	Registry URL where the agent pushes the config image
`DOCKER_CONFIG`	—	Path to Docker config directory (for private registries)

Docker socket and privileged mode

The agent container requires:

Docker socket (/var/run/docker.sock) — the agent runs docker compose up --build to validate test assets locally before pushing them to Antithesis.
Privileged mode — required for Docker-in-Docker operations.

See Security for the security implications of this setup.

White-list repositories

In the interest of avoiding spam the agent has to white-list repositories before the oracle will accept test-runs for them.

Two commands are available

White-list a repository

This will only work if the repository is not already white-listed and the repository is in GitHub.

moog agent white-list --platform <platform> --repository <repository>

ATM only GitHub is supported as a platform. The format of the repository is <owner>/<repository>, e.g. cardano-foundation/moog.

Black-list a repository

This will only work if the repository is white-listed.

moog agent black-list --platform <platform> --repository <repository>

Query pending test-runs

The agent is responsible for managing test-runs from pending to running and completed.

moog facts test-runs pending --pretty

will report all the pending test runs in a human friendly format.

Download a test-run assets

Once a test-run is pending the agent can download the assets for the test-run.

moog agent download-assets -i <test-run-id> -D <directory>

This will download the assets for the test-run with id <test-run-id> into the directory <directory>.

Start a test-run locally

At the moment there is no moog-cli command to start a test-run locally. But a minimal check could be done via docker compose.

cd <directory>
INTERNAL_NETWORK=true docker compose up --build

Obviously you should do all kind of analysis you deem necessary on the assets before deciding the next step.

Reject a test-run

If the agent decides a test-run is not acceptable it can reject it.

moog agent reject-test -i <test-run-id> --reason <reason>

Push a test-run to antithesis platform

Once decided a test-run is acceptable the agent can push the test-run to the antithesis platform.

moog agent push-test -i <test-run-id> -D <directory>

This will push the test-run with id <test-run-id> to the antithesis platform

Report the acceptance of a test-run on-chain

Once a test-run is pushed to the antithesis platform the agent has to report the acceptance of the test-run on-chain.

moog agent accept-test -i <test-run-id>

This will move it from pending to running state in the facts.

Check for the completion of a test-run

The agent service derives test results from the Antithesis REST API: it matches each on-chain accepted test-run to an Antithesis run by its description and finishes it when the run reaches a terminal status. You can inspect the same API data manually with the moog antithesis subcommands (see the Antithesis proxy page):

moog antithesis runs --limit 100 --no-pretty
moog antithesis run --run-id <run-id>
moog antithesis properties --run-id <run-id>

Legacy: collecting results via email

Earlier versions collected results from the Antithesis notification emails. The email-based commands still exist but are no longer on the result path of the agent service:

export MOOG_AGENT_EMAIL="<your-email>"
moog agent collect-results-for --test-run-id <test-run-id> --minutes <n> --ask-agent-email-password

HAL Team

To use your CF email you have to use an app password. If you use your password you will get an error like

LoginFailed user error (NO: Application-specific password required: https://support.google.com/accounts/answer/185833 (Failure))

Just go to https://myaccount.google.com/apppasswords and create an app password.

Report the completion of a test-run on-chain

Once the result URL is retrieved the agent has to report the completion of the test-run on-chain.

moog agent report-test -i <test-run-id> --url <result-url>  --duration <duration-in-hours>

The URL is encrypted automatically with the requester's public key.