Use cases

Xianyun brings up a production-like local cluster from a shared configuration. Three jobs follow from that.

Validating a change

You or your agent need a real environment to check a feature, reproduce a bug, or demo a workflow, and you want it to be disposable. A shared xianyun.yaml, with optional fragments, lets a less technical contributor turn features on with a one-line change, and Xianyun wraps the technical steps: starting the cluster, trusting a CA, and setting up hostnames.

This is the job Xianyun is built around, and it’s why the MCP server exists: an agent runs validate, bring up, check, reads the results, and decides what to do next.

Developing against production-mode services

Deploying services as Helm charts and Kustomize overlays closes most of the gap between development and production. Edit mode lets a developer run only the code they’re changing against that cluster, so xianyun run swaps the relevant production service for the local process.

The first part works: deployers install into a real cluster. The second doesn’t yet, because the edit-mode supervisor stops after its preflight checks. See Known limitations.

Test environments

The same configuration can stand up an ephemeral environment for automated tests. A suite only needs an endpoint: an API URL, an HTTP address for browser tests, or xianyun kubectl for lower-level checks. The setup in CI has three parts: a container runtime (k3d on a Linux runner), the xianyun binary, and xianyun up followed by your suite and xianyun destroy.

There’s no published release, so a CI job has to build Xianyun or fetch a build you produce. I haven’t run Xianyun in CI as an end-to-end test; the repository’s own end-to-end coverage is the e2e-mock and e2e-k3d NixOS VM tests described in Testing.