Agent VM — define an AI agent once, run it on any runtime.
English | Simplified Chinese
AVM (avm) is a local config manager for AI coding agents. You build a
reusable Agent — instructions, skills, MCP servers, runtime preferences —
and AVM applies it to whichever target runtime you launch. AVM owns the
managed config, reports what each runtime can natively express, and keeps the
files you hand-edit out of its way.
The objects you'll see day-to-day:
- Agent — your reusable working profile; the only object you create or edit directly.
- Capability — a skill or MCP server an Agent references. AVM discovers the ones already installed in your runtimes and imports them.
- Package — a
.avm.zipbundle exporting an Agent (and its capabilities) for sharing or reinstalling. - Runtime — the target tool that actually runs the Agent.
AVM ships as two binaries that pair together:
avm— the Go CLI, non-interactive plumbing. Every command takes flags or stdin, emits human text or--json. Use it from scripts and CI.avm-ui— the TypeScript full-screen TUI inui/that shells out toavmover the JSON contract. Use it for interactive editing and browsing.
The current architecture source of truth lives in
docs/engineering/architecture-overview.md.
curl -fsSL https://raw.githubusercontent.com/xz1220/AVM/main/scripts/install.sh | shThe installer is the one-command first-run path. It installs avm and
avm-ui into $HOME/.local/bin, runs avm setup to initialize ~/.avm
and import existing runtime capabilities, and installs shell integration
for bash, zsh, or fish when it can detect your shell.
Installer options:
AVM_INSTALL_DIR="$HOME/.local/bin" # binary install directory
AVM_INSTALL_UI=0 # CLI-only install
AVM_SKIP_SETUP=1 # install binaries only
AVM_INSTALL_SHELL_INTEGRATION=0 # do not edit shell rc files
AVM_SETUP_ARGS="--runtime codex" # forwarded to avm setupavm-ui currently requires Node.js 22 or newer. Set AVM_INSTALL_UI=0
for a CLI-only install.
To build from source:
make build # bin/avm
make build-ui # ui/dist/avm-ui.js (interactive TUI)
make build-allThe first time you use AVM on a machine, import whatever your runtimes already have so Agents can reference them:
avm capability bootstrap --runtime claude-code
avm capability bootstrap --runtime codex
avm capability listFlag-driven (the CLI never prompts; use avm-ui if you want a wizard):
avm agent create \
--name backend-coder \
--runtime codex \
--description "API + DB work on the order service" \
--skill git --skill testavm list
avm agent list # lower-level Agent CRUD list
avm agent show backend-coder
avm agent show backend-coder --runtime codex # how each field maps to the runtime
avm agent edit backend-coder --skill git --skill test --skill review
avm agent clone backend-coder --name backend-reviewer
avm agent rename backend-reviewer reviewer
avm agent delete reviewer --yesagent edit is non-interactive: any list flag (--skill, --mcp,
--runtime) replaces the current list. To preserve current values, read
them first with avm agent show <name> --json.
avm use backend-coder --runtime codex --drift discard
avm run # uses the active profile
avm run backend-coder
avm run backend-coder --runtime codex # one-run override
avm run backend-coder --preview # show the plan; do not launch
avm run backend-coder --drift merge # acknowledge drift between AVM and existing managed config
avm defaults # inspect sticky defaults
avm defaults explain # show where run values come fromavm run propagates the runtime's exit code so shell scripts can branch on
it. Sticky defaults are stored under ~/.avm/preferences.yaml; AVM does not
write them into your project directory.
avm package export backend-coder -o backend-coder.avm.zip
avm package install ./backend-coder.avm.zip --on-conflict rename
avm package inspect ./backend-coder.avm.zip
avm package list
avm package uninstall backend-coder --yesavm doctor # AVM home, runtimes, recent runs
avm status [agent]
avm runtime list # registered runtimes with availabilityEvery command above accepts --json and emits a model from
internal/app/model/. The exact JSON shape, error
codes, and exit-code semantics live in docs/api/cli-protocol.md.
AVM renders the selected Agent into runtime-specific managed files. Each
driver reports every Agent field as native, rendered_as_instructions,
ignored, or unsupported — avm agent show <name> --runtime <rt> shows
the full mapping.
| Runtime | Status | Notes |
|---|---|---|
| Codex | Supported | Native profile/model/reasoning mapping; isolated CODEX_HOME per run |
| Claude Code | Supported | Agent frontmatter, MCP, skills; pruned auth state carried into the boundary |
| OpenCode | Supported | Config, agent, skills, and MCP mapping |
| OpenClaw | In progress | Runtime research complete (docs/.../openclaw-runtime.md); driver not yet implemented |
| Hermes Agent | In progress | Target runtime; driver not yet implemented |
AVM is released under the PolyForm Noncommercial License 1.0.0.
In plain language:
- You may copy, modify, distribute, and learn from this code for any non-commercial purpose — personal projects, research, education, evaluation, hobby use, and use by non-profit organizations.
- Commercial use requires a separate license from the project owner.
- The software is provided "as is", without warranty.
If you'd like to use AVM commercially, open an issue or contact the maintainer.
Thanks to everyone who has helped build AVM.