Credential Vault

The credential vault stores secrets encrypted at rest using AES-256-GCM. Agents never have access to credentials directly. The vault key lives in the tool executor process. When a tool needs credentials, the infrastructure resolves them from the vault and injects them into the API call.

This architecture ensures that even if an agent's context is leaked or logged, no secrets are exposed. The entire credential lifecycle — decryption, injection, and cleanup — happens in a layer the agent cannot observe.

The credential vault uses a proxy pattern to keep secrets out of agent context. The agent only sees business parameters in and a sanitized result out. At no point does the agent have access to any token, API key, or credential. The entire credential lifecycle happens in the tool executor layer.

Agent
  -> tool("create_issue", { repo, title })
    -> Tool Executor
      -> Vault.resolve("github_token")
        -> HTTP call with token
          -> sanitized result
            -> Agent

Environment Variable

Set MAXIMUS_VAULT_KEY as an environment variable. This is the master key used to derive the encryption key (via scrypt) for encrypting and decrypting credentials.

# Linux/macOS
export MAXIMUS_VAULT_KEY="your-secure-vault-key-here"

# Or in a .env file (never commit to git)
MAXIMUS_VAULT_KEY=your-secure-vault-key-here

Storage Recommendations

Interactive Fallback

For local development, if MAXIMUS_VAULT_KEY is not set and the process is running in an interactive terminal (TTY), the engine will prompt for the vault key. This fallback is disabled in non-interactive environments (CI, background processes) where stdin.isTTY is false.

Enter vault key (MAXIMUS_VAULT_KEY): _

Create & Populate a Vault

Use the CredentialVault API to add credentials programmatically:

import { CredentialVault } from "@maximus/vault";

// Create or open a vault
const vault = new CredentialVault(process.env.MAXIMUS_VAULT_KEY!);

// Add credentials
vault.set("github_token", "ghp_your_token_here", {
  description: "GitHub PAT with repo scope",
});

vault.set("slack_webhook", "https://hooks.slack.com/services/T00/B00/xxx", {
  description: "Slack webhook for #engineering channel",
});

// Save encrypted vault to disk
vault.save("config/credentials.enc");

Load & Manage

Load an existing vault, list stored credentials (metadata only), check existence, or remove entries:

const vault = CredentialVault.load("config/credentials.enc", process.env.MAXIMUS_VAULT_KEY!);

// List stored credentials (metadata only, no values)
const creds = vault.list();
// [{ name: "github_token", description: "...", createdAt: "...", updatedAt: "..." }]

// Check if a credential exists
vault.has("github_token"); // true

// Remove a credential
vault.delete("github_token");

Skills reference credentials by name. The ref must match the name used in vault.set(). At tool execution time, template variables are replaced with decrypted values from the vault. The agent never sees the actual token value.

# In a skill YAML file
credentials:
  - ref: github_token
    inject_as: GITHUB_TOKEN

tools:
  - name: github_create_issue
    credentials:
      - ref: github_token
        inject_as: GITHUB_TOKEN
    action:
      type: http
      method: POST
      url: "https://api.github.com/repos/{{repo}}/issues"
      headers:
        Authorization: "Bearer {{GITHUB_TOKEN}}"

Tool output is automatically sanitized to strip leaked secrets before being returned to the agent. The sanitizer runs as a PostToolUse hook on every SDK session. Patterns are ordered from specific to generic to minimize false positives.

The credential vault implements a three-layer defense ensuring credentials remain secure throughout the entire agent lifecycle: at rest, during execution, and in output.

Credentials are encrypted using AES-256-GCM with a key derived from the vault key via scrypt (with a random salt). Each credential gets its own random initialization vector (IV), preventing identical plaintext from producing identical ciphertext.

Credentials are never present in the agent's context. The CredentialProxy resolves credentials from the vault only at tool execution time, in the tool executor process. The vault key itself is blocked from the SDK subprocess environment.

Even if a credential somehow appears in a tool's output (e.g., an error message containing a token), the PostToolUse sanitizer hook catches and redacts it before the output reaches the agent. The regex pipeline processes patterns from most-specific to most-generic to minimize false positives.

Together, these three layers ensure that credentials remain secure throughout the entire agent lifecycle: at rest (encrypted on disk), during execution (proxy pattern isolates the agent), and in output (sanitizer catches any leaks before they reach the context window).