{"slug": "show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses", "title": "Show HN: VAEN – Package and import portable AI coding-agent Harnesses", "summary": "VAEN, a portable command-line tool for packaging and importing portable AI coding-agent configurations, has been released. The tool bundles instructions, skills, and MCP declarations into an OCI-backed `.agent` archive that can be imported into another repository without transporting secrets, addressing the gap between simple file transfer and explicit setup handoffs.", "body_md": "VAEN is a portable CLI for packaging and importing agentic coding setups.\n\nIt takes an `agent.yaml`\n\nmanifest, bundles instructions, skills, and project-scoped MCP declarations into an OCI-backed `.agent`\n\narchive, and imports that setup into another repository without transporting secrets.\n\nWatch the 24-second flow: [docs/assets/vaen-demo.mp4](/sjhalani7/vaen/blob/main/docs/assets/vaen-demo.mp4)\n\n```\nvaen validate -f agent.yaml\nvaen build -f agent.yaml -o team-setup.agent\nvaen inspect team-setup.agent\nvaen import team-setup.agent --client codex\nvaen doctor --client codex\n```\n\nVAEN packages configuration and authoring files, not runtime environments.\n\n- Main instructions and optional instruction includes\n- Skill directories and their files\n- Project-scoped MCP declarations\n- Bundle metadata used for import, inspection, and validation\n\nVAEN never packages credential values, `.env`\n\nfiles, private keys, OAuth state, or MCP server implementations.\n\nA zip file can move files, but it does not explain what the setup is, what should be imported, where files should land, or which credential variable names the receiver must provide locally.\n\nVAEN keeps that handoff explicit:\n\n`agent.yaml`\n\ndeclares the instructions, skills, MCP declarations, and required variable names.`vaen validate`\n\ncatches malformed manifests before sharing.`vaen inspect`\n\nlets the receiver review bundle contents before import.`vaen import`\n\nmaterializes the setup into predictable client-specific locations.`vaen doctor`\n\nchecks the imported structure without reading credential values.\n\nInstall from GitHub with `pipx`\n\n:\n\n```\npipx install git+https://github.com/sjhalani7/vaen.git\n```\n\nOr install from a local clone:\n\n```\npython3 -m venv .venv\n. .venv/bin/activate\npip install -e .\n```\n\nThe CLI provides:\n\n``` python\nvaen validate\nvaen build\nvaen inspect\nvaen import\nvaen doctor\nvaen cleanup\n```\n\nSee [docs/quick-start.md](/sjhalani7/vaen/blob/main/docs/quick-start.md) for a minimal instructions-only bundle flow.\n\nThe [ dist/agents/](/sjhalani7/vaen/blob/main/dist/agents) directory contains ready-to-import\n\n`.agent`\n\narchives for popular, reputable public agent setups.Current packages:\n\n— complete promoted skill set from`mattpocock-skills.agent`\n\n`mattpocock/skills`\n\n— engineering skills`mattpocock-engineering.agent`\n\n— productivity skills`mattpocock-productivity.agent`\n\n— misc utility skills`mattpocock-misc.agent`\n\nSee [ dist/agents/README.md](/sjhalani7/vaen/blob/main/dist/agents/README.md) for import commands and attribution.\n\n`agent.yaml`\n\nis the source of truth for a bundle.\n\n```\nversion: \"0.1\"\npublisher: \"Shiv Jhalani\"\n\ninstructions:\n  main: \"~/.codex/AGENTS.md\"\n  includes:\n    - \"./style.md\"\n\nartifacts:\n  - type: skills\n    path: \"~/.codex/skills/code-review\"\n  - type: skills\n    path: \"~/.codex/skills/refactor\"\n\nrequiredVars:\n  - OPENAI_API_KEY\n\nmcp:\n  servers:\n    - name: context7\n      transport: stdio\n      command: npx\n      args: [\"-y\", \"@upstash/context7-mcp\"]\n      env_vars:\n        - CONTEXT7_API_KEY\n\n    - name: docs\n      transport: http\n      url: https://example.com/mcp\n      http_headers:\n        X-Region: us-east-1\n      bearer_token_env_var: DOCS_MCP_TOKEN\n      header_env_vars:\n        X-API-Key: DOCS_MCP_TOKEN\n```\n\nManifest rules:\n\n`version`\n\n,`publisher`\n\n, and`instructions.main`\n\nare required.`instructions.includes`\n\nis optional.`artifacts`\n\nis a list and may be empty for instructions-only bundles.`skills`\n\nis the supported artifact type.`requiredVars`\n\nand MCP env fields store environment variable names only, never values.- Manifest authors are responsible for writing names such as\n`OPENAI_API_KEY`\n\n, not credential values such as API keys, tokens, URLs with passwords, or`NAME=value`\n\nassignments. `http_headers`\n\nstores non-secret static HTTP headers for MCP servers.`mcp`\n\nis optional and lives at the top level of the manifest.- Source paths may point inside or outside the repo.\n\nCorrect:\n\n```\nrequiredVars:\n  - OPENAI_API_KEY\n\nmcp:\n  servers:\n    - name: docs\n      transport: http\n      url: https://example.com/mcp\n      bearer_token_env_var: DOCS_MCP_TOKEN\n```\n\nIncorrect:\n\n```\nrequiredVars:\n  - OPENAI_API_KEY=sk-proj-secret\n  - sk-proj-secret\n\nmcp:\n  servers:\n    - name: docs\n      transport: http\n      url: https://user:password@example.com/mcp\n      bearer_token_env_var: sk-proj-secret\n```\n\nMCP support is host-neutral in the manifest. During import, VAEN writes the selected client format for Codex, Claude Code, or Copilot.\n\nInstructions only:\n\n```\nversion: \"0.1\"\npublisher: \"Your Name\"\n\ninstructions:\n  main: \"./AGENTS.md\"\n\nartifacts: []\n```\n\n`instructions.main`\n\npoints to`AGENTS.md`\n\nor another main agent instruction file.\n\nInstructions with skills:\n\n```\nversion: \"0.1\"\npublisher: \"Your Name\"\n\ninstructions:\n  main: \"./AGENTS.md\"\n  includes:\n    - \"./style.md\"\n\nartifacts:\n  - type: skills\n    path: \"./skills/code-review\"\n  - type: skills\n    path: \"./skills/refactor\"\n```\n\n`instructions.includes`\n\nis for extra Markdown instruction/context files.- Each\n`artifacts`\n\nentry points to one skill directory.\n\nMCP servers:\n\n```\nversion: \"0.1\"\npublisher: \"Your Name\"\n\ninstructions:\n  main: \"./AGENTS.md\"\n\nartifacts: []\n\nmcp:\n  servers:\n    - name: context7\n      transport: stdio\n      command: npx\n      args: [\"-y\", \"@upstash/context7-mcp\"]\n      env_vars:\n        - CONTEXT7_API_KEY\n    - name: figma\n      transport: http\n      url: \"https://mcp.figma.com/mcp\"\n      bearer_token_env_var: FIGMA_OAUTH_TOKEN\n      http_headers:\n        X-Figma-Region: us-east-1\n```\n\n`name`\n\nis the local MCP server name.`transport`\n\nis either`stdio`\n\nor`http`\n\n.`command`\n\nand`args`\n\ndefine how stdio MCP servers are launched.`url`\n\ndefines the HTTP MCP endpoint.`env_vars`\n\nand`bearer_token_env_var`\n\ncontain environment variable names only, never secret values.`http_headers`\n\ncontains non-secret static headers.\n\n```\nvaen validate -f examples/synthetic-fixture/agent.yaml\nvaen build -f examples/synthetic-fixture/agent.yaml\n```\n\nIf `-o`\n\nis omitted, VAEN writes `<manifest-directory-name>.agent`\n\nin the working directory:\n\n``` php\nexamples/synthetic-fixture/agent.yaml -> synthetic-fixture.agent\n```\n\nYou can choose the archive name:\n\n```\nvaen build -f examples/synthetic-fixture/agent.yaml -o shiv-setup.agent\n```\n\nExplicit output paths must end in `.agent`\n\n.\n\n```\nvaen inspect synthetic-fixture.agent\n```\n\n`inspect`\n\nreads the OCI archive and prints bundle metadata, normalized bundle paths, instructions, skills, MCP declarations, and required variable names.\n\nIn the target repo:\n\n```\nvaen import /path/to/synthetic-fixture.agent\n```\n\nIf the bundle contains MCP declarations, select the client config to write:\n\n```\nvaen import /path/to/synthetic-fixture.agent --client codex\nvaen import /path/to/synthetic-fixture.agent --client claude\nvaen import /path/to/synthetic-fixture.agent --client copilot\n```\n\nDefault import (no `--client`\n\nand no target override flags) writes root instructions to `AGENTS.md`\n\nand `CLAUDE.md`\n\n, and mirrors skills to `.agent/skills/...`\n\nand `.claude/skills/...`\n\n.\n\nIf `--client`\n\nis provided and none of `--target`\n\n, `--target-instructions-file-name`\n\n, `--target-skills-directory`\n\nare provided, activated outputs default to the client:\n\n`--client claude`\n\n:`CLAUDE.md`\n\nand`.claude/skills/...`\n\n`--client codex`\n\n:`AGENTS.md`\n\nand`.codex/skills/...`\n\n`--client copilot`\n\n:`AGENTS.md`\n\nand`.copilot/skills/...`\n\nTo target another agent directory:\n\n```\nvaen import /path/to/synthetic-fixture.agent --target copilot\n```\n\nThis writes `COPILOT.md`\n\nand `.copilot/skills/...`\n\n.\n\nOptional import overrides:\n\n```\nvaen import /path/to/synthetic-fixture.agent --target copilot --target-instructions-file-name copilot-instructions\nvaen import /path/to/synthetic-fixture.agent --target copilot --target-skills-directory vscode\n```\n\nThese write `copilot-instructions.md`\n\nand `.vscode/skills/...`\n\n.\n\n```\nvaen doctor\n```\n\nUse the same targeting and MCP client flags that were used during import:\n\n```\nvaen doctor --client codex\nvaen doctor --target copilot --client copilot\nvaen doctor --target copilot --target-instructions-file-name copilot-instructions\nvaen doctor --target copilot --target-skills-directory vscode\n```\n\n`doctor`\n\nvalidates the imported structure and reports required environment variable names as warnings.\n\nAfter confirming the activated files look right, remove the canonical stored copy:\n\n```\nvaen cleanup /path/to/synthetic-fixture.agent\n```\n\nCleanup deletes `.agent/<bundle-name>`\n\nonly. It does not delete root instruction files, skill mirrors, or MCP client config.\n\nA `.agent`\n\nfile is an OCI-style archive:\n\n```\nbundle.agent\n├── oci-layout\n├── index.json\n└── blobs/sha256/\n    ├── <manifest blob>\n    ├── <config blob>\n    └── <layer blob>\n```\n\nThe layer blob is a tar payload:\n\n```\nvaen/metadata.json\ninstructions/...\nskills/...\nmcp/...\n```\n\nPath terminology:\n\n`source path`\n\n: where a file lives on the builder's machine`bundle path`\n\n: where that file is stored inside the`.agent`\n\n`materialized path`\n\n: where that file is written during import\n\nThis lets a builder reference files from places like `~/.codex/AGENTS.md`\n\nwhile keeping the bundle layout stable and machine-independent.\n\nImport writes a canonical stored copy first:\n\n```\n.agent/<bundle-name>/\n├── instructions/\n├── mcp/\n├── skills/\n└── vaen/metadata.json\n```\n\nThen it writes activated files for the target repo:\n\n- Root instruction files:\n`AGENTS.md`\n\nand`CLAUDE.md`\n\n, or the configured target filename. - Skill mirrors:\n`.agent/skills/...`\n\nand`.claude/skills/...`\n\n, or the configured target skill directory. - MCP client config:\n`.codex/config.toml`\n\n,`.mcp.json`\n\n, or`.github/mcp.json`\n\nwhen`--client`\n\nis used.\n\nIncluded instruction files remain in `.agent/<bundle-name>/instructions/...`\n\n; they are not concatenated into the root instruction file.\n\nVAEN fails before overwriting existing setup files.\n\n- Existing root instruction files block import.\n- Existing\n`.agent/<bundle-name>`\n\ndirectories block import. - Existing mirrored skill names block import.\n- Existing MCP client config files block import.\n\nSkill directories should contain only instructions, scripts, references, and assets needed by the agent. Do not place credential files such as `.env`\n\n, `.env.*`\n\n, private keys, or credential stores inside a skill directory before building a bundle.\n\nBuild rejects obvious declared secret file paths such as `.env`\n\n, `.env.*`\n\n, `*.pem`\n\n, `*.key`\n\n, and `id_rsa`\n\n. Detected secret values are never printed.\n\nCredential handling is metadata-only:\n\n`requiredVars`\n\nand MCP env fields store variable names only.`doctor`\n\ndoes not read`.env`\n\nfiles.`doctor`\n\ndoes not inspect shell environment variables, keychains, or other credential stores.- MCP validation checks local config syntax and expected file placement; it does not connect to MCP servers or validate auth.\n\nThe test fixture is a compact reference manifest:\n\nThe project-specific example is here:\n\nVAEN is released under the MIT License.\n\nThe software is provided as-is, without warranty of any kind. The authors and copyright holders are not liable for claims, damages, or other liability arising from use of the software. See [LICENSE](/sjhalani7/vaen/blob/main/LICENSE) for the full license text.", "url": "https://wpnews.pro/news/show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses", "canonical_source": "https://github.com/sjhalani7/vaen", "published_at": "2026-05-27 20:52:31+00:00", "updated_at": "2026-05-27 21:14:39.991335+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "ai-infrastructure"], "entities": ["VAEN", "OCI", "Codex"], "alternates": {"html": "https://wpnews.pro/news/show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses", "markdown": "https://wpnews.pro/news/show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses.md", "text": "https://wpnews.pro/news/show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses.txt", "jsonld": "https://wpnews.pro/news/show-hn-vaen-package-and-import-portable-ai-coding-agent-harnesses.jsonld"}}