update
May 27, 2026
By Teun
VAEN packages portable AI coding-agent setups into .agent archives
VAEN is a CLI that packages agent.yaml-based coding-agent setups into OCI-backed .agent archives and imports them into other repositories without secrets. It validates manifests, inspects bundle contents, and writes client-specific files for Codex, Claude Code, or Copilot.
VAEN is a new command-line tool for packaging and moving agentic coding setups between repositories. According to its author, Shiv Jhalani, it takes an agent.yaml manifest and bundles instructions, skills, and project-scoped MCP declarations into an OCI-backed .agent archive that can later be imported elsewhere.
The project is aimed at people who want to share an AI coding agent setup without shipping secrets, runtime state, or machine-specific assumptions. VAEN packages configuration and authoring files only, not the runtime environment. That includes main instructions, optional included Markdown files, skill directories and their contents, project-scoped MCP declarations, and bundle metadata used for import, inspection, and validation.
⚡ New to this?
This is about a packaging format for AI coding agents. An agentic coding setup is the combination of instructions, skills, and tool connections that tell an AI assistant how to work inside a codebase.
MCP stands for Model Context Protocol, a way for an agent to connect to external tools or services. VAEN matters because it tries to move that setup in a repeatable way without copying secrets or assuming the same machine layout.
🦞 OpenClaw angle
If you build self-hosted agent setups, treat agent.yaml as the source of truth and keep secrets out of the bundle. Put only environment variable names in manifests, never values, and add a preflight check in your own automation before export so .env, key files, and secret stores are excluded.
If you distribute agent templates across repos, use a two-step import flow like VAEN’s: first inspect the bundle, then write client-specific files. That pattern reduces accidental overwrite and makes it easier to support Codex, Claude, and Copilot-style directory layouts from one internal packaging pipeline.
For teams, store reusable skills and instructions in portable bundles, but keep MCP server implementations and credentials deployed separately on the target machine. That gives you a cleaner handoff between automation authors and operators while preserving local control over secrets and tool runtime.
The tool is explicit about what it will not carry over. According to the project description, VAEN never packages credential values, .env files, private keys, OAuth state, or MCP server implementations. Instead, the manifest stores environment variable names only, such as OPENAI_API_KEY or CONTEXT7_API_KEY, so the receiving user knows which values they need to supply locally.
VAEN’s workflow starts with validation. The CLI offers vaen validate, vaen build, vaen inspect, vaen import, vaen doctor, and vaen cleanup. Validation checks for malformed manifests before sharing, while build creates the .agent archive and inspect prints bundle metadata, normalized paths, instructions, skills, MCP declarations, and required variable names.
Import is where the setup gets materialized into a target repository. VAEN writes the canonical stored copy first under .agent/<bundle-name>/, then writes activated files for the selected client. According to the project docs, default import writes root instructions to both AGENTS.md and CLAUDE.md, while client-specific imports can target Codex, Claude, or Copilot directories and file names.
The project also supports MCP, short for Model Context Protocol, which is used here to describe external tools an agent can talk to. VAEN’s manifest can declare stdio or HTTP MCP servers, along with non-secret static HTTP headers and environment variable names for credentials. During import, the selected client format is written for Codex, Claude Code, or Copilot.
The bundle format is OCI-style, using an archive structure with oci-layout, index.json, and blob layers. The layer payload holds vaen/metadata.json, instructions/, skills/, and mcp/, which lets the bundle remain portable across machines while keeping the source paths separate from the materialized paths written into a repository.
VAEN also includes safety checks to avoid accidental overwrite. According to the documentation, existing root instruction files, existing .agent/<bundle-name> directories, existing mirrored skill names, and existing MCP client config files all block import. Cleanup removes only the stored canonical copy and does not delete root instruction files, skill mirrors, or MCP client config.
The project is available from GitHub via pipx install git+https://github.com/sjhalani7/vaen.git, or from a local clone using a Python virtual environment and pip install -e .. The repository also includes ready-to-import .agent archives for several public agent setups under dist/agents/.
