Workflows

These are loops an agent can run today. Each step is one tool call.

Validate, bring up, check

1. xianyun_config_validate. A schema error names the field. Fix it before anything else.
2. xianyun_doctor. It reports environment problems it knows about.
3. xianyun_up. This starts the cluster through the configured driver and waits for its API.
4. xianyun_status. Confirms the state.
5. When you’re done, ask the human to approve xianyun_down, or xianyun_destroy for a clean slate.

up and down are idempotent. Calling xianyun_down on a cluster that was never started succeeds, so an agent doesn’t need to check first.

Read results properly

A call can fail at two levels. If the client reports a tool error without running anything, the server refused the call, as it does for a gated tool on an older client. If the call ran and the command failed, the result has a non-zero exit_code and the reason in stderr. Retry logic should look at exit_code, not only at whether the call returned.

xianyun_status prints nothing and exits 0 when no cluster has been started, so an empty result means “stopped”, not “broken”.

Inspect a running environment

• xianyun_registry_status with {"output": "json"} returns the image cache state as JSON: whether zot is running, its port, and the upstreams.
• xianyun_logs returns edit-mode process output. Pass process names in args and a tail flag to bound the output.
• xianyun_ca_inspect shows the dev CA’s path, subject, and which name constraints it enforces.

Keep repositories current

xianyun_update with {"verify_only": true} reports what would change without touching any repository. Call it before a real update, and read the output: a repository whose fast-forward isn’t possible is reported and left alone.

Limits today

Be honest with your agent about what doesn’t work yet, or it will spend turns on it.

• The builtin:dev-ca and builtin:traefik-tlsstore overlays haven’t been deployed end to end, though the helm, kustomize, and namespace deployers have. See Known limitations.
• Edit mode (xianyun run) isn’t available over MCP and is only partly implemented in the CLI.
• Gated tools need a client that supports elicitation.