Xianyun
Xianyun starts a local Kubernetes cluster, installs what your project’s config lists into it, and sets up the host so the cluster is usable: a trusted dev certificate authority, hostnames in /etc/hosts, a kube context, and an optional pull-through image cache. It’s built for validation work, where you bring an environment up, check a change against it, and tear it down again, over and over.
The main way to use it is through an AI agent. xianyun-mcp is an MCP server that hands a reviewed set of Xianyun commands to your agent as tools. The same commands are available from a terminal as xianyun, so you and the agent work against the same environment with the same vocabulary.
Two binaries
| Binary | What it is |
|---|---|
xianyun-mcp | The MCP server. It speaks MCP on standard input and output, and each tool call runs the matching xianyun command and returns its output. |
xianyun | The command-line tool. Every MCP tool maps to one of its commands. |
xianyun-mcp is the whole CLI plus the MCP server, because tool calls re-run the same executable. You can install just xianyun-mcp and still get the terminal commands.
Where to start
- Use it with an agent. Install, then connect an agent. Read Confirmation and gated tools before you rely on the destructive tools.
- Use it from a terminal. Set up a first project, then the command reference.
- Write a config. Configuration overview and the reference.
- Contribute or audit. Project documentation holds the architecture decisions, the specification, the user stories, and the threat model. The API reference is generated by rustdoc.
Status
Xianyun is alpha software. It’s a Rust rewrite of Caproni, the Go tool it forked from, and parity isn’t complete. Read Known limitations before you plan a workflow around it. The most important ones: edit mode is only partly implemented, and the built-in dev CA and Traefik TLS overlays haven’t been deployed end to end.
This book describes the xianyun binary. The documentation in the repository’s docs/ directory describes the original Go binary and its names.
About the name
Xianyun (閑雲, pinyin Xián Yún) means “idle cloud”. It’s also the name of the Genshin Impact adeptus who designs and builds tools, like the Steam Bird, for others to use safely, which is a fair description of the job.