Getting Started

1. Define a permission profile (YAML)
2. An AVP-compliant tool creates a session
3. Credentials are loaded from the vault + host environment
4. Each credential is evaluated against the profile rules
5. Access decisions are logged to the audit trail
6. The agent runs in a filtered environment
7. Session ends → marked inactive

name: moderate
description: "Allow dev variables, redact cloud secrets"
trustLevel: 50
ttlSeconds: 3600
rules:
  - pattern: "*"          # Start by denying everything
    access: deny
  - pattern: NODE_ENV     # Allow specific dev variables
    access: allow
  - pattern: DEBUG
    access: allow
  - pattern: AWS_*        # Redact all AWS credentials
    access: redact
  - pattern: OPENAI_*     # Redact API keys
    access: redact

id         - Auto-incremented identifier
sessionId  - Links to the active session (UUID)
agentId    - Identifies the agent
profileName - Profile used for evaluation
varName    - Credential name evaluated
action     - "allow", "deny", or "redact"
timestamp  - ISO 8601 timestamp

.agentvault/
├── profiles/          # Permission profile YAML files
│   ├── restrictive.yml
│   ├── moderate.yml
│   └── permissive.yml
├── vault.json         # Encrypted credentials
├── memory.json        # Encrypted agent memory
├── sessions.json      # Active sessions
├── audit.db           # SQLite audit trail
├── mcp-budget.json    # Rate limit budget
├── purchased-banks/   # Memory banks
├── .passphrase        # Encryption key (mode 0600)
└── .gitignore         # Prevents accidental commits

function matchRule(varName, pattern):
    if pattern == "*":
        return true                          // wildcard matches everything
    if pattern ends with "*":
        prefix = pattern[0 .. length-2]      // strip trailing *
        return varName starts with prefix    // prefix match
    return varName == pattern                // exact match

function checkAccess(profile, varName):
    result = "deny"                         // default if no rules match
    for each rule in profile.rules:         // iterate in declaration order
        if matchRule(varName, rule.pattern):
            result = rule.access            // overwrite with latest match
    return result                           // "allow", "deny", or "redact"

function generateRedactionToken():
    randomBytes = crypto.randomBytes(8)     // 8 bytes minimum entropy
    hex = randomBytes.toHex()               // 16 hex characters
    return "VAULT_REDACTED_" + hex

// Example output: VAULT_REDACTED_a1b2c3d4e5f6a7b8
// Each redaction generates a UNIQUE token — never reuse tokens

function sandboxAgent(profile, agentCommand):
    session = createSession(profile.name, agentCommand)
    credentials = loadVault() + loadHostEnvironment()
    filteredEnv = {}

    for each (name, value) in credentials:
        if name in SYSTEM_VARS:             // PATH, HOME, USER, SHELL, etc.
            filteredEnv[name] = value        // passthrough, not logged
            continue

        decision = checkAccess(profile, name)
        auditLog(session.id, name, decision) // log BEFORE enforcement

        if decision == "allow":
            filteredEnv[name] = value
        else if decision == "redact":
            filteredEnv[name] = generateRedactionToken()
        // "deny" → variable excluded entirely

    // Inject session metadata
    filteredEnv["AGENTVAULT_SESSION"] = session.id
    filteredEnv["AGENTVAULT_PROFILE"] = profile.name
    filteredEnv["AGENTVAULT_TRUST"]   = str(profile.trustLevel)

    // Spawn agent as child process with filtered environment
    spawnChildProcess(agentCommand, env=filteredEnv)
    onExit: markSessionInactive(session.id)

// Request
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "vault.secret.get",
    "arguments": { "key": "OPENAI_API_KEY" }
  },
  "id": 1
}

// Success response
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"success\": true, \"data\": { \"key\": \"OPENAI_API_KEY\", \"value\": \"sk-abc123...\" } }"
    }]
  },
  "id": 1
}

// Error response (key not found)
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "{ \"success\": false, \"error\": \"Key not found\", \"code\": \"KEY_NOT_FOUND\" }"
    }],
    "isError": true
  },
  "id": 1
}