AVPAgent Vault Protocol
Choose a LevelLevel 1: CoreLevel 2: FullLevel 3: ExtendedCommon MistakesTestingMigration Guide

Implementation Guide

Building an AVP-Compliant Tool

A step-by-step guide to implementing the Agent Vault Protocol in your agent, framework, or tool.

Choose Your Conformance Level

AVP defines three levels. Pick the one that fits your use case.

LevelTarget Use Case
Level 1 — CoreIDE extensions, local dev tools, simple agents
Level 2 — FullCI/CD pipelines, production agents, security-conscious tools
Level 3 — ExtendedDistributed systems, MCP-based services, memory marketplaces

Start with Level 1. It covers the core access control model and can be implemented in a few days. You can incrementally add Level 2 and 3 features later without breaking changes.

Level 1: Core

Profile parsing, rule evaluation, sandbox filtering, and audit logging.

Level 1 is the minimum viable AVP implementation. It requires four things:

1. Parse YAML profiles

Read .agentvault/profiles/*.yml files. Validate name (lowercase + hyphens), trustLevel (0–100), ttlSeconds (integer ≥ 0), and rules array.

2. Implement pattern matching

Support three patterns: wildcard (*), prefix (PREFIX_*), and exact (NAME). No regex. The matchRule function is ~10 lines.

3. Evaluate rules with last-match-wins

Iterate rules in order, overwrite the decision on each match. Default is "deny" if no rules match. System variables (PATH, HOME, etc.) always pass through.

4. Log every decision to an audit trail

Before applying the decision, append to the audit trail: sessionId, agentId, profileName, varName, action, timestamp. Use SQLite or append-only JSON.

Level 1 — complete sandbox in pseudocode(pseudocode)
SYSTEM_VARS = ["PATH", "HOME", "USER", "SHELL", "TERM", "LANG",
               "LC_ALL", "TMPDIR", "NODE_PATH"]

function sandbox(profile, agentCmd):
    env = getHostEnvironment()
    filtered = {}

    for (name, value) in env:
        if name in SYSTEM_VARS:
            filtered[name] = value
            continue

        decision = "deny"
        for rule in profile.rules:
            if matchRule(name, rule.pattern):
                decision = rule.access

        audit.append(sessionId, name, decision, now())

        if decision == "allow":
            filtered[name] = value
        elif decision == "redact":
            filtered[name] = "VAULT_REDACTED_" + randomHex(8)

    spawn(agentCmd, env=filtered)
That's it:Level 1 is intentionally simple. The core algorithm is under 50 lines in any language. If you can parse YAML and spawn a child process, you can implement Level 1.

Level 2: Full

Encrypted vault, sessions, memory, and TTL enforcement.

Level 2 adds encryption and state management on top of Level 1. Build these in order:

1. Encrypted vault

Store credentials in vault.json encrypted with AES-256-GCM. Derive key from passphrase using scrypt (N=16384, r=8, p=1). Use a random 32-byte salt per file and a new random IV on every write.

2. Session management

Create a session (UUID v4) when an agent starts. Track agentId, profileName, pid, startedAt, active status. Inject AGENTVAULT_SESSION, AGENTVAULT_PROFILE, AGENTVAULT_TRUST into the agent's environment.

3. TTL enforcement

Monitor session duration. When ttlSeconds is exceeded, send SIGTERM to the agent process and mark the session inactive. Implement a kill switch that revokes all active sessions.

4. Encrypted memory

Store agent memory in memory.json using the same AES-256-GCM encryption. Support three memory types: knowledge, query_cache, operational. Enforce 10,000 entry / 50 MB limits.

5. Memory search

Extract keywords from queries (lowercase, tokenize, filter < 3 chars, remove stopwords, max 40). Score entries using: matchRatio × confidence × freshnessMultiplier × recencyBoost. Support O(1) query hash cache hits via SHA-256.

6. Standard directory structure

Create .agentvault/ with profiles/, vault.json, memory.json, sessions.json, audit.db, .passphrase (mode 0600), and .gitignore containing * and !.gitignore.

Level 3: Extended

Portable vaults, memory banks, licensing, and MCP server.

Level 3 adds interoperability and distribution features:

1. Portable vault format

Export credentials and/or memories to .avault files encrypted with an independent passphrase. Support both agentvault-portable/1.0 (full) and agentvault-memory/1.0 (memory-only) schemas.

2. Memory banks & licensing

Support distributable memory collections with bank descriptors and license enforcement. Implement five license types: unlimited, time_locked, access_limited, time_and_access, subscription. Check license validity before returning bank entries.

3. MCP server interface

Expose 11 tools via Model Context Protocol: vault.secret.get/list, vault.memory.store/query/list/remove, vault.audit.show, vault.status, vault.profile.show, vault.preview, vault.export. Support stdio transport (required) and SSE (optional, requires TLS in production).

4. Graceful shutdown

On SIGTERM/SIGINT: stop accepting connections → drain in-flight requests (5 second max) → flush rate limit budget to disk → release file locks → exit with code 0.

Common Mistakes

Pitfalls to avoid when implementing AVP.

Logging after enforcement

Audit entries MUST be written BEFORE the access decision is applied. If you log after, a crash between enforcement and logging creates a gap in the audit trail.

First-match-wins instead of last-match-wins

AVP uses last-match-wins (like .gitignore). A common bug is breaking on the first match instead of iterating all rules. Always iterate the entire rules array.

Reusing redaction tokens

Each redacted variable must get a unique cryptographically random token. Never reuse tokens across variables or sessions — this would allow correlation attacks.

Forgetting system variable passthrough

PATH, HOME, USER, SHELL, TERM, LANG, LC_ALL, TMPDIR, and NODE_PATH must always pass through unconditionally. Without these, the child process won't start.

Hardcoded or default passphrases

Never ship a default passphrase. Passphrase resolution order: environment variable → .passphrase file → interactive prompt. Empty values at any stage must fall through to the next.

Shared IV across writes

Generate a new random IV on every write to vault.json or memory.json. Reusing an IV with AES-GCM completely breaks the encryption.

Running agent in-process

The agent MUST run as a child process, not in the same process. In-process execution would give the agent access to the unfiltered environment via process.env or equivalent.

Testing Your Implementation

How to verify conformance with the AVP specification.

The AVP repository includes test vectors covering 10 areas:

Test AreaWhat to Verify
Pattern matchingWildcard, prefix, and exact patterns return correct match/no-match
Rule evaluationLast-match-wins semantics produce the correct access decision
System variable bypassSystem vars pass through regardless of profile rules
Redaction formatTokens match VAULT_REDACTED_<hex> with sufficient entropy
Keyword extractionTokenization, stopword removal, deduplication, max 40 limit
Query hashSHA-256 of normalized query matches stored queryHash for O(1) lookup
Scoring algorithmmatchRatio × confidence × freshness × recencyBoost produces expected scores
Session injectionAGENTVAULT_SESSION, AGENTVAULT_PROFILE, AGENTVAULT_TRUST are injected correctly
Portable vault validationSchema field, exportedAt, entries/memories arrays validated on import
Encryption envelopesalt, iv, tag, data fields present; decryption with correct passphrase succeeds
Conformance:Run all test vectors for your target conformance level. Level 1 requires pattern matching, rule evaluation, system bypass, and redaction. Level 2 adds keyword extraction, scoring, session injection, and encryption. Level 3 adds portable vault validation.

Migration Guide

Adopting AVP if you currently use .env files or environment variables directly.

If your tool currently reads credentials from environment variables or .env files, here's how to adopt AVP incrementally:

Step 1: Start with a permissive profile

Create a profile that allows everything (pattern: *, access: allow). This is functionally identical to your current behavior but adds audit logging. Zero credential disruption.

Step 2: Add audit logging

Wrap your agent execution with AVP sandbox evaluation. Log every access decision. Run for a few days and review the audit trail to understand which credentials your agent actually uses.

Step 3: Tighten the profile

Based on audit data, create a moderate profile that allows only the credentials your agent needs. Redact cloud credentials, deny unused variables. Deploy and monitor.

Step 4: Add encryption (Level 2)

Move sensitive credentials from .env into the encrypted AVP vault. Your agent now retrieves secrets from the vault at runtime, filtered through the active profile.

Step 5: Add session management

Enable TTLs and session tracking. This gives you revocation capability and bounded execution contexts.

Key principle:AVP is designed for incremental adoption. You can start with Level 1 (audit-only) and progressively add encryption, sessions, and memory without changing your agent's code.

Ready to implement?

Read the full specification for complete schemas, algorithms, and conformance requirements.

Full SpecificationView Examples