Your agent needs to log in, call an API, or run a command—not receive your password. MagicVault delivers stored credentials to an approved browser field, HTTP request or new process. The agent uses references and gets a status receipt, not the secret.

This protects MagicVault's own tool calls and replies. Authorized recipients see the credential, and separate browser tools can still read it afterward.

[!WARNING] Source alpha. No public release or npm registry installation yet; local candidate packages only. Basic installed-browser/keychain/native-consent and selected remembered-use, permission/recovery and cancellation cases passed on one macOS/Chrome setup. Broader recovery, startup/process-delivery reliability and signed-release qualification remain open. Start with synthetic credentials. Evidence and limits.

How it works

1. You enroll and authorize through native prompts—not chat.
2. The agent requests a use with secure_fill, secure_new_http or secure_new_process, passing references instead of values.
3. You control consent. Approve each delivery or explicitly remember an exact use with Always allow. MagicVault checks the destination and returns a receipt. Your browser tool still owns navigation and submission.

Use MCP with Codex, Claude Code or another local agent. Prefer the CLI for shell scripts, or the builder interfaces for applications and extensions.

Quick start

Requires macOS Apple Silicon, a logged-in desktop session and Node.js 22+ for npm launchers. No Rust toolchain is needed to use prebuilt candidates. This is local stdio MCP—not a hosted endpoint or unattended credential access.

1. Install a local candidate and enroll

Obtain two matching, trusted tarballs from a maintainer or the candidate build instructions. These are local filenames, not published npm package names.

export MAGICVAULT_NPM_DIR="$HOME/.local/share/magicvault-npm"
npm install --prefix "$MAGICVAULT_NPM_DIR" --ignore-scripts \
  ./magicvault-local-magicvault-darwin-arm64-0.8.3.tgz \
  ./magicvault-local-magicvault-0.8.3.tgz
export PATH="$MAGICVAULT_NPM_DIR/node_modules/.bin:$PATH"
magicvault --profile agent setup
magicvault --profile agent doctor
magicvault --profile agent enroll --label 'Demo account' --field password
magicvault --profile agent list-credentials

Explicit setup, not npm, installs the app/service/native host and initializes custody/pairing. Enter a synthetic password only in the hidden prompt. Keep the daemon running. Installation, upgrades and removal.

2. Connect your agent

Choose your client. These commands use the default paths and paired profile agent; custom installations should use the configuration printed by setup. MCP does not start the daemon or bypass native consent.

Consent modes and revocation: per-use is the default; only the human can create an exact-use Always allow grant. Website access is separate.

# Codex
codex mcp add magicvault -- "$HOME/.magicvault-app/current/bin/magicvault-mcp" \
  --profile agent
codex mcp list

# Claude Code (user-wide configuration)
claude mcp add --transport stdio --scope user magicvault -- \
  "$HOME/.magicvault-app/current/bin/magicvault-mcp" --profile agent
claude mcp get magicvault

Start a new agent session and ask for vault_status and list_credentials. Other clients and configuration. Client references: Codex, Claude Code.

3. Authorize a destination and use it

For a browser without CDP, use Developer mode → Load unpacked in chrome://extensions and select setup's extension_directory. Choose website access and approve the matching browser profile ID. Connection is automatic. Full extension instructions.

For an automation browser, register its loopback CDP websocket instead; no extension is needed. Authorize the field for the exact trusted origin:

# Replace both placeholders with your reference and trusted test-page origin.
magicvault --profile agent configure-browser-credential \
  --credential-ref cred_REPLACE_WITH_ENROLLED_UUID \
  --field password --origin https://accounts.example.com

After opening that page with your browser tool, ask your agent:

Use MagicVault to find my Demo account and the correct browser tab. Fill its password field with secure_fill, then poll the operation's status. Never retrieve or type the password through another tool.

For HTTP or commands, register a fixed destination profile instead, then ask the agent to use secure_new_http or secure_new_process. Every delivery requires your approval. filled/completed does not prove login or application success. Never automatically repeat a missing or uncertain operation.

What works today

HTTP supports GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE and supported custom methods; no CONNECT, redirects or automatic retries. Process output and HTTP response content are withheld. Headless browsers still need the daemon's human-approval desktop. Full coverage, frame conditions and limits.

CLI for agents and scripts

MCP is optional. The CLI exposes secure-fill, secure-new-process and secure-new-http under magicvault, with the same paired daemon and native consent. CLI recipes cover discovery, reference-only request files, status polling and cancellation. Scripts cannot approve themselves.

Build on MagicVault

Embed the Rust custody/effect crates, use the authenticated local protocol, or implement the native bridge in your existing Chromium extension. These handle plaintext and must preserve authorization. No Python/Node SDK is shipped. Builder guide.

Rust toolchain

Source builds use Rust edition 2021; standalone MCP requires compiler 1.88+. Build and foreground-service instructions include SSD1 artifact routing. Shared custody remains independent of the standalone CLI/MCP; embedded-consumer compatibility.

Security: the promise and its boundary

MagicVault keeps enrolled values out of its supported agent-facing requests, replies, errors and audit projections. It does not hide credentials from the approved recipient, independent browser observations or unrestricted same-user software. Password masking is not an observation filter. Threat model and private reporting.

Documentation and contributing

Documentation index · Architecture and drift baseline · Usage and coverage · Qualification and runbooks · Changelog · Versions

For issues, include the interface, version and OS/browser with a synthetic reproduction. Never upload vaults, pairing files, live credentials or raw traces.

License

MIT OR Apache-2.0.