User Manual

Secrets exist but are never observable.

Contents

1. Installation

Open Your Terminal

On Mac: Press Cmd + Space, type "Terminal", press Enter.
On Linux: Press Ctrl + Alt + T

Install (One Command)

~ % curl -fsSL https://phantomvault.riscent.com/install | sh

  Detecting system...
  ✓ macOS 15.3 (Apple Silicon M4)

  Downloading phantom-vault v1.0.0...
  ✓ Downloaded (4.2 MB)

  Installing to /usr/local/bin/phantom...
  ✓ Installed

  🔐 Phantom Vault is ready.
  Run 'phantom init' to create your vault.

Verify It Worked

~ % phantom --version
phantom-vault 1.0.0

2. Your First 5 Minutes

Step 1: Create Your Vault

~ % phantom init

  Creating new vault at ~/.vault-secrets

  Enter master password: ••••••••••••••••
  Confirm master password: ••••••••••••••••

  Vault created successfully!

  Next steps:
    phantom add <name>     Add a secret
    phantom mcp install    Enable Claude Code integration
    phantom biometric enable   Enable Touch ID unlock

With Touch ID (macOS)

~ % phantom init --biometric

  Creating new vault at ~/.vault-secrets

  Enter master password: ••••••••••••••••
  Confirm master password: ••••••••••••••••

  Enabling biometric unlock...
  Touch ID enabled for vault unlock.

  Vault created successfully!

What just happened? Phantom created an encrypted vault using AES-256-GCM with Argon2id key derivation. With --biometric, your password is stored in macOS Keychain protected by Touch ID.

Step 2: Add Your First Secret

~ % phantom add OPENAI_API_KEY
Enter value for OPENAI_API_KEY: ••••••••••••••••••••••••••••••••
✓ Added OPENAI_API_KEY

Step 3: Connect to Claude Code

~ % phantom mcp install

  Installing MCP server for Claude Code...
  ✓ Config written to ~/Library/Application Support/Claude/claude_desktop_config.json

  Done. Restart Claude Code, then ask:
  "What secrets do I have in my vault?"

3. Adding Secrets

Interactive (Secure — Value Hidden)

~ % phantom add STRIPE_SECRET_KEY
Enter value: ••••••••••••••••••••••••
✓ Added STRIPE_SECRET_KEY

From Environment

~ % export TEMP_KEY="sk_live_abc123"
~ % phantom add STRIPE_KEY --from-env TEMP_KEY
✓ Added STRIPE_KEY
~ % unset TEMP_KEY

With Expiration

~ % phantom add TEMP_TOKEN --expires 7d
Enter value: ••••••••••••
✓ Added TEMP_TOKEN (expires in 7 days)

4. Viewing Your Secrets

List All Secrets (Names Only)

~ % phantom list

  Namespace: default

  NAME                 CREATED      EXPIRES     ACCESS
  OPENAI_API_KEY       2 days ago   never       12 times
  STRIPE_SECRET_KEY    1 day ago    never       3 times
  DATABASE_URL         5 hours ago  never       8 times

Notice: Values are never shown. Even phantom list only shows names.

See Last 4 Characters (Verification)

~ % phantom show STRIPE_SECRET_KEY --masked
STRIPE_SECRET_KEY: ••••••••••••xyz9

5. Using with AI Agents

Connect to Claude Code

~ % phantom mcp install

After restarting Claude Code, your AI gets these tools:

Example: Ask Claude to Deploy

# You say:
"Deploy my app to Railway using my RAILWAY_TOKEN"

# Claude runs:
vault_run(keys: ["RAILWAY_TOKEN"], command: "railway up")

# Output is sanitized — if the token leaked, you'd see:
Deploying with token [REDACTED:RAILWAY_TOKEN]...

6. Running Commands

Inject Secrets as Environment Variables

~ % phantom run -s OPENAI_API_KEY -- python my_script.py
✓ Running with 1 secret injected
(your script runs with OPENAI_API_KEY in its environment)

Multiple Secrets

~ % phantom run -s DATABASE_URL -s REDIS_URL -- node server.js

Security: The secrets only exist in that subprocess. When it exits, they're gone. Output is scanned for leaked secrets and redacted automatically.

7. Namespaces

Keep work and personal secrets separate:

~ % phantom namespace create work
~ % phantom namespace use work
~ % phantom add COMPANY_API_KEY

~ % phantom namespace use default  # switch back

8. Health & Rotation

Check Vault Health

~ % phantom health

  Vault Status: Healthy

  Secrets: 5 total
  Expiring soon: 1
    - TEMP_TOKEN (expires in 2 days)

  Last audit entry: 3 minutes ago
  Canary status: OK

Rotate a Secret

~ % phantom rotate STRIPE_SECRET_KEY
Enter new value: ••••••••••••••••••••••••
✓ Rotated STRIPE_SECRET_KEY (v1 → v2)
✓ Old value securely erased

9. Audit Log

~ % phantom audit --last 10

  TIME                  EVENT           SECRET              TOOL
  2026-02-27 14:23:01   accessed        OPENAI_API_KEY      vault_run
  2026-02-27 14:20:15   accessed        DATABASE_URL        vault_run
  2026-02-27 13:05:44   added           STRIPE_SECRET_KEY   cli
  2026-02-27 12:00:00   vault_opened    -                   cli

Every access is logged with HMAC chaining — tampering is detectable.

10. Canary Secrets

Honeypot secrets that alert you if something tries to use them:

~ % phantom canary create BACKUP_AWS_KEY --pattern aws-access-key
✓ Created canary BACKUP_AWS_KEY
  Looks like: AKIA••••••••••••XXXX
  ⚠ Alert will trigger if this is ever accessed

11. Biometric Unlock

On macOS, you can unlock your vault with Touch ID instead of typing your password every time.

Check Status

~ % phantom biometric status

  Biometric Authentication Status
  ================================

  [OK] Touch ID is available
  [OK] Biometric unlock is enabled for this vault

Enable Touch ID

~ % phantom biometric enable
  Enter master password to enable biometric: ••••••••••••

  Biometric unlock enabled!
  You can now unlock with Touch ID.

Disable Touch ID

~ % phantom biometric disable
  Biometric unlock disabled.
  You will need to use your password to unlock the vault.

How it works: Your master password is stored in macOS Keychain, protected by Touch ID. When you authenticate with Touch ID, the password is retrieved from Keychain and used to unlock the vault. The password never leaves the secure enclave.

12. Security Policies

Control which tools can access your secrets and set usage restrictions.

View Current Policy

~ % phantom policy show

  Security Policy:
  ================

  require_confirmation = ["shell_exec"]

  (Using default policy)

Create a Policy File

# my-policy.toml
allowed_tools = ["exec_sql", "http_request", "vault_run"]
blocked_tools = ["shell_exec"]
require_confirmation = ["write_file"]
rate_limit = 100  # max 100 secret accesses per hour

[time_restrictions]
enabled = true
start_hour = 9
end_hour = 18
timezone = "America/New_York"

Apply a Policy

~ % phantom policy set my-policy.toml
Security policy updated from 'my-policy.toml'

New policy:
allowed_tools = ["exec_sql", "http_request", "vault_run"]
blocked_tools = ["shell_exec"]
...

Reset to Defaults

~ % phantom policy reset
Reset security policy to defaults? [y/N]: y
Security policy reset to defaults.

Policy Priority: blocked_tools takes precedence over allowed_tools. If a tool is in both lists, it will be blocked.

13. Cheat Sheet

# Setup
phantom init                    # Create vault
phantom init --biometric        # Create vault + enable Touch ID
phantom mcp install             # Connect to Claude

# Secrets
phantom add SECRET_NAME         # Add secret (interactive)
phantom add KEY --from-env VAR  # Add from environment
phantom list                    # List all secrets
phantom show NAME --masked      # Show last 4 chars
phantom get NAME                # Get full value (TTY only)
phantom remove NAME             # Delete secret
phantom rotate NAME             # Rotate secret
phantom import .env             # Import from .env file

# Running commands
phantom run -s KEY -- cmd       # Inject secret into command

# Biometric (macOS)
phantom biometric status        # Check Touch ID status
phantom biometric enable        # Enable Touch ID
phantom biometric disable       # Disable Touch ID

# Namespaces
phantom namespace list          # List namespaces
phantom namespace create NAME   # Create namespace
phantom namespace use NAME      # Switch namespace
phantom namespace delete NAME   # Delete namespace

# Canary secrets
phantom canary create NAME      # Create honeypot secret
phantom canary list             # List canaries
phantom canary delete NAME      # Delete canary

# Security policies
phantom policy show             # View current policy
phantom policy set FILE         # Apply policy from file
phantom policy reset            # Reset to defaults

# Maintenance
phantom health                  # Check vault health
phantom audit --last N          # View last N audit entries
← Back to Home