Autovault

AutoVault

=22" src="https://img.shields.io/badge/node-%3E%3D22-339933">

[ SKILL.md ] -> [ validate ] -> [ sign ] -> [ scope ] -> [ render ]

A local-first vault for the skills your agents actually use.

~48-second demo — dashboard and terminal use simulated skills and data.

SKILL.md files already move through GitHub repos, team docs, public indexes, Slack threads, and agent-written drafts. AutoVault gives those files one canonical home: validate them at admission time, sign what passes, track where they came from, and render the right view for each agent without maintaining forks by hand.

AutoVault is a Node/TypeScript capability library, CLI, and MCP server. It has local stdio and remote Streamable HTTP MCP entry points, both backed by the same filesystem vault and SQLite capability index.

It does not execute skills through the MCP server. The server validates and serves skill content; the host agent decides how to use that content inside its own tool sandbox. The separate user-invoked autovault skill CLI can run signed bin: actions from installed skills, and that surface is documented under [Security Model](#security-model).

Docs and public site:

Why AutoVault

The SKILL.md format is intentionally plain. The hard part is everything around it:

• Skill drift - the same skill gets copy-pasted into Claude Code, Codex,

Cursor, and project folders with no upstream tracking.

• Supply-chain risk - remote skill bytes should be treated like untrusted

package contents until they pass a gate.

• Duplicate explosion - agents can author near-identical skills unless new

proposals are deduplicated before storage.

• Platform mismatch - one agent says read, another says file_read, and a

third expects a different filesystem tool name.

• Scope leakage - local dev skills should not silently show up in prod or in

another client's project.

AutoVault's answer is deliberately simple: keep one canonical skill folder, record provenance, sign the admitted content, and sync or serve agent-specific views from that source.

Quick Start

Requirements:

• Node.js >=22.0.0
• curl, tar, and npm
• macOS 13+, Linux x64/arm64, or Windows through WSL2

Install the local vault:

curl -fsSL https://autovault.sh | sh
export PATH="$HOME/.autovault/bin:$PATH"
autovault --version
autovault doctor
autovault setup --review
autovault skill list

Install with Homebrew:

brew install autoworks-ai/tap/autovault
autovault setup

Install the packaged CLI/library directly from npm:

npm install -g @autoworks-ai/autovault
autovault setup --review
autovault doctor

Manual source install:

git clone https://github.com/autoworks-ai/autovault.git
cd autovault
npm ci
npm run build
node scripts/bootstrap-skills.mjs
node dist/cli.js doctor

The shell installer builds the app under ~/.autovault/app, preserves ~/.autovault as user-owned vault storage, installs the autovault CLI shim, and bootstraps bundled skills unless AUTOVAULT_NO_BOOTSTRAP=1 is set. By default it installs the latest stable release; set AUTOVAULT_REF=main only when you explicitly want the unreleased main branch.

What Ships Today

AutoVault supports:

• local filesystem storage under AUTOVAULT_STORAGE_PATH
• a SQLite capability index for callers, profiles, tool groups, aliases,

context rules, and MCP servers

• per-agent and tag-filtered profile symlink generation
• vault-local skill transforms that render agent-specific variants without

forking upstream SKILL.md

• install, update, proposal, bulk-import, removal, resource-read, and drift-check

workflows

• enrolled pull-sync foundations for signed upstream skill releases, including

metadata-only update checks, local approval policy, bundle verification, and revocation state

• source adapters for GitHub, agentskills, arbitrary HTTPS URLs, local bundles,

and inline MCP-proposed content

• three-tier deduplication for proposals
• Ed25519 signatures and manifest checks for stored skills and executable

resources

• local stdio MCP and remote Streamable HTTP MCP at /mcp with OAuth-backed

bearer auth

The npm package and Homebrew formula are live. The shell installer is still the easiest local bootstrap path because it provisions ~/.autovault, installs the CLI shim, and seeds bundled skills in one pass.

Distribution:

• Source and releases:
• NPM package page:
• Homebrew tap:
• Container image: ghcr.io/autoworks-ai/autovault:

CLI Surface

The CLI is the local operator surface:

autovault add  [--source github|agentskills|url|local] [--provenance ] [--version ] [--agent ] [--sync-profiles|--no-sync-profiles] [--discover|--no-discover] [--link agent=/path/to/skills] [--dry-run] [--yes] [--quiet] [--verbose] [--json]
autovault add-local  [--source ] [--sync-profiles] [--link agent=/path/to/skills] [--json]
autovault remove  [--discover|--no-discover] [--link agent=/path/to/skills] [--json]
autovault sync-profiles [--discover] [--link agent=/path/to/skills] [--json]
autovault profiles list [--json]
autovault setup [--json] [--review] [--advanced]
autovault doctor [skill-name] [--clean] [--repair] [--json]
autovault audit-repo --repo /path/to/repo [--format json|markdown]
autovault import-autohub --tool-filters /path/tool-filters.json [--mcp-servers /path/mcp-servers.json] [--reset] [--json]
autovault init  [--json]
autovault resolve --caller  --platform  [--channel ] --query  [--json]
autovault serve [--help]
autovault ui [--port ] [--no-open]
autovault skill list [--json]
autovault skill search  [--top-k N] [--json]
autovault skill which  []
autovault skill  

Human-readable output is the default. Use --json or --format json only for scripts and other machine consumers.

autovault ui starts a loopback-only browser dashboard for local skill metadata edits, named profile management, profile sync, update checks, deletion, signed upstream update installs, enrolled-client revocation, and permission-group visibility. It serves the packaged React assets and uses the same /api/v1 management API shape as remote AutoVault.

autovault init enrolls the local vault with a signed upstream catalog. The first implementation supports file-backed catalogs for local testing and future cloud adapters; downloaded resources still install through AutoVault's existing validation, manifest, and profile-sync paths.

Common flows:

# Inspect vault health and integrity.
autovault doctor
autovault doctor --clean
autovault doctor --repair

# Add a known skill from any supported source.
autovault add ./path/to/your-skill --sync-profiles
autovault add ./path/to/your-skill/SKILL.md --sync-profiles
autovault add https://github.com/org/repo/tree/main/skills/your-skill
autovault add owner/repo:skills/your-skill/SKILL.md
autovault add my-skill --source agentskills
autovault add https://example.com/SKILL.md --source url

# Search installed skills locally.
autovault skill search code-review --top-k 5

# Enroll a local test upstream and review signed updates in the dashboard.
autovault init ./path/to/upstream-catalog
autovault ui

# Remove a vaulted skill and refresh managed profile links.
autovault remove skill-author

autovault add is the canonical terminal path for known skills from local bundles, GitHub repositories, agentskills slugs, or HTTPS URLs. Existing installer scripts can keep using add-local as a compatibility alias for local bundles; there, --source still means local provenance. For new local adds, omit provenance and AutoVault records the normalized absolute bundle directory. If a remote skill omits AutoVault-specific agents frontmatter, pass --agent codex (repeatable) for profile sync, or --no-sync-profiles for a vault-only install.

autovault setup is the first-run adoption wizard. It scans the vault, bundled skills, and discovered native roots such as ~/.claude/skills, ~/.codex/skills, and ~/.cursor/skills, then asks how to adopt each skill. Run it from a real terminal; without a TTY the installer defers setup and tells you to rerun the wizard manually.

MCP Tool Surface

MCP hosts can spawn the local stdio server with node dist/index.js, while remote clients connect to dist/remote.js at /mcp.

Registered tools:

• get_skill - search by query or fetch by exact name, optionally rendering for

an agent and including packaged resources.

• add_skill - install a known skill from github, agentskills, url, or

local.

• propose_skill - submit newly authored SKILL.md bytes for validation,

security scan, deduplication, signing, and storage.

• bulk_import - import every immediate child directory containing a SKILL.md.
• update_skill - refresh from the recorded source or replace from a new

source, local bundle, or inline bytes.

• delete_skill - remove an installed skill and its vault-local transforms,

then refresh generated profiles.

• check_updates - compare installed skills against upstream source state and

report drift or transform-review work.

Tool handlers return plain objects. src/mcp/server.ts wraps and serializes them into the MCP content[0].text envelope. Remote mode applies an additional policy layer for scopes and skill visibility.

Library Surface

The source package exports the same helpers used by the CLI and MCP server:

• resolveCapabilities() / resolve_capabilities()
• syncProfiles() and discoverProfileRoots()
• addSkill(), updateSkill(), deleteSkill(), installSkill(),

addLocalSkill(), proposeSkill(), and bulkImport()

• proposeSkillTransform(), listSkillTransforms(),

removeSkillTransform(), and renderSkillForAgent()

• auditRepo()
• importAutohubCapabilities() / ensureAutohubSeeded()

Unknown callers fail closed. Register callers explicitly or map unknown users to a restricted caller such as guest.

Validation Gate

Every install, update, proposal, and bulk import runs through the same validation path:

1. Repair and normalize frontmatter formatting.
2. Parse YAML frontmatter with gray-matter.
3. Validate schema with zod.
4. Scan content against the denylist in scripts/security/patterns.json.
5. Cross-check declared capabilities against observed behavior.
6. Deduplicate exact, near-exact, and functionally similar proposals.
7. Write the skill, source sidecar, signed manifest, and Ed25519 signature.

In strict mode (AUTOVAULT_SECURITY_STRICT=true, the default), denylist hits block writes. In non-strict mode they become warnings.

Storage Layout

Default storage is ~/.autovault; override it with AUTOVAULT_STORAGE_PATH.

$AUTOVAULT_STORAGE_PATH/
  autovault.sqlite             # capability index
  .signing-key.json            # Ed25519 keypair, mode 0600
  skills/
    /
      SKILL.md
      .autovault-source.json   # source, hash, timestamps
      .autovault-signature     # detached Ed25519 signature, mode 0600
      .autovault-manifest      # signed manifest for declared resources/bin
      
  transforms/
    //
      TRANSFORM.md
      BASE_SKILL.md
      .autovault-transform.json
      .autovault-manifest
  rendered/
    //            # generated variants
  profiles/
    / -> ../../skills/ or ../../rendered//
    / -> ../../skills/ or ../../rendered//
  profiles.config.json
  cloud-sync/
    upstreams.json             # enrolled upstream/device metadata, mode 0600

Skills are plain files. Back them up like dotfiles:

tar -czf autovault-backup-$(date +%F).tgz -C "$HOME" .autovault

Skill Transforms

Transforms let a workspace or agent adjust a skill without editing the upstream SKILL.md. AutoVault stores the transform under the vault, appends transform instructions to the base skill at render time, applies declared capability metadata overrides, and materializes generated variants under rendered/.

Example TRANSFORM.md:

---
name: perplexity
base: research-skill
description: Use Perplexity instead of the default web search path.
targets:
  agents: [codex]
priority: 100
capability_overrides:
  network: true
  tools:
    add: [mcp__perplexity__search]
    remove: [web_search]
metadata:
  version: "1.0.0"
---

Use `mcp__perplexity__search` instead of `web_search` for research.

When the base skill changes, check_updates continues rendering the transform but returns transform_reviews with the pinned old base so the delta can be reviewed.

Remote Deploy

Remote mode is for a shared or managed vault. It serves Streamable HTTP MCP at /mcp, uses OAuth for client registration/login/token issuance, and stores the vault under the mounted AUTOVAULT_STORAGE_PATH.

npm run build
AUTOVAULT_MODE=remote \
AUTOVAULT_PUBLIC_URL=http://localhost:3000 \
AUTOVAULT_ADMIN_EMAIL=admin@example.com \
AUTOVAULT_ADMIN_PASSWORD=replace-with-a-long-random-password \
npm run start:remote

Docker:

AUTOVAULT_ADMIN_EMAIL=admin@example.com \
AUTOVAULT_ADMIN_PASSWORD=replace-with-a-long-random-password \
docker compose up --build

Remote mode cannot create symlinks on client machines. sync-profiles is local-only because a remote MCP server has no filesystem access to ~/.codex/skills, ~/.claude/skills, or other host roots. Remote clients should discover and read skills directly through get_skill.

Configuration

Runtime environment:

| Variable | Default | Purpose | | --- | --- | --- | | AUTOVAULT_MODE | local | local for stdio/library use, remote for HTTP MCP. | | AUTOVAULT_STORAGE_PATH | ~/.autovault | Root path for installed skills. | | AUTOVAULT_DB_PATH | $AUTOVAULT_STORAGE_PATH/autovault.sqlite | SQLite capability index. | | AUTOVAULT_PROFILE_LINKS | unset | Comma-separated agent=/skills/root links for profile sync. | | AUTOVAULT_PROFILE_CONFIG_PATH | $AUTOVAULT_STORAGE_PATH/profiles.config.json | Optional named profile config. | | AUTOVAULT_SKILL_INSTALL | prefer-autovault | Vendor routing: prefer-autovault, both, native, native-only, or off. | | AUTOVAULT_SECURITY_STRICT | true | Block denylist hits when true; warn when false. | | AUTOVAULT_SEARCH_MODE | text | Search backend. Metadata text search is the current implementation. | | AUTOVAULT_LOG_LEVEL | info | debug, info, warn, or error. | | AUTOVAULT_LOG_DIAGNOSTICS | unset | Set to 1 to let structured diagnostic logs pass through public CLI output suppression. | | AUTOVAULT_PUBLIC_URL | required in remote mode | Public origin for OAuth metadata and callbacks. | | AUTOVAULT_HTTP_PORT | 3000 | HTTP port when PORT is not injected by the platform. | | AUTOVAULT_ALLOWED_ORIGINS | unset | Optional CORS allowlist for remote mode. | | AUTOVAULT_ADMIN_EMAIL | required until owner exists | First remote owner email. | | AUTOVAULT_ADMIN_PASSWORD | required until owner exists | First remote owner password, at least 12 characters. | | GITHUB_TOKEN | unset | Optional GitHub API rate-limit headroom. | | AUTOVAULT_AGENTSKILLS_BASE | https://agentskills.io/api/v1 | Override the agentskills API base. |

Installer-only environment:

| Variable | Default | Purpose | | --- | --- | --- | | AUTOVAULT_HOME | ~/.autovault | Install root for app, shim, and default storage. | | AUTOVAULT_BIN_DIR | $AUTOVAULT_HOME/bin | Directory for the autovault shim. | | AUTOVAULT_REF | latest stable release | GitHub branch or tag downloaded by autovault.sh; use main for the unreleased branch. | | AUTOVAULT_TARBALL_URL | derived from AUTOVAULT_REF | Fully override the source archive URL. | | AUTOVAULT_NO_BOOTSTRAP | 0 | Set to 1 to skip bundled-skill bootstrap. |

Security Model

AutoVault has two execution surfaces with different boundaries.

The MCP servers (dist/index.js over stdio and dist/remote.js over Streamable HTTP) are storage-and-validation services. They never execute skill content. Remote sources are treated as

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: autoworks-ai
• Source: autoworks-ai/autovault
• License: MIT
• Homepage: https://autovault.dev

Install and usage instructions live in the source repository linked above.