Familiar logo
Familiar usefamiliar.com
Documentation / Fleet

Secure Vault

Store and manage sensitive credentials securely.

Secure Vault

The Secure Vault is Fleet's encrypted credential storage system that keeps your API keys, passwords, tokens, and other sensitive data secure on your machine. Secrets stored in the vault are never exposed to AI providers, never appear in conversation history, and are automatically masked in tool outputs.

What is the Vault?

The vault is a secure storage layer that sits between your agents and your operating system's native credential manager. When you store a secret in Fleet's vault, it's encrypted and saved using macOS Keychain — the same system that stores your passwords, certificates, and credit cards in Safari and other macOS apps.

Key characteristics:

  • Zero-knowledge architecture — The AI model never sees secret values, only names
  • OS-level encryption — Uses macOS Keychain with AES-256-GCM encryption
  • Hardware-backed security — On Macs with Secure Enclave (T2 or Apple Silicon), encryption keys are hardware-protected
  • User-scoped access — Only your macOS user account can decrypt and access your secrets
  • Automatic masking — Secret values are stripped from all tool outputs before they're shown to you or the AI

Where Are Secrets Stored?

Secrets are stored in macOS Keychain, your operating system's native credential storage. Specifically:

  • Service name: familiar
  • Account name format: vault-secret-YOUR_SECRET_NAME
  • Access control: Restricted to your macOS user account
  • Location: Keychain items are stored in ~/Library/Keychains/ but managed entirely by macOS

What this means:

  • You can view your vault secrets in the macOS Keychain Access app (Applications → Utilities → Keychain Access)
  • Secrets persist across Fleet updates and reinstalls
  • If you reset your Mac or change users, the secrets are protected by macOS user account encryption
  • Secrets are backed up with Time Machine (encrypted) if you back up your Keychain
  • No secrets are stored in Fleet's database or configuration files

Who Can Access Your Secrets?

✅ Can Access

Your macOS user account

  • You can view and manage secrets through Fleet's UI (Settings → Security → Secure Vault)
  • You can view secrets in Keychain Access app (search for service "familiar")
  • Any process running as your user that knows the service name and account name

Fleet backend (running as you)

  • The Fleet backend process runs as your user and can read secrets from the Keychain
  • It only reads secrets when replacing {{vault:SECRET_NAME}} placeholders in tool calls
  • Secrets are immediately masked in tool outputs before being stored or displayed

❌ Cannot Access

AI providers (Claude, OpenAI, etc.)

  • Secrets are replaced in tool arguments after the AI generates the tool call
  • The AI only ever sees the placeholder syntax ({{vault:SECRET_NAME}}), never actual values
  • Tool outputs are masked before being sent back to the AI

Other macOS users

  • Keychain items are scoped to your user account
  • Other users on the same Mac cannot access your secrets

Sub-agents and child processes

  • Sub-agents inherit the same vault access as their parent (they run in the same backend)
  • However, the AI model controlling the sub-agent never sees the secret values

Fleet's conversation history

  • Secrets are masked before being stored in the database
  • If you export conversation history, secrets appear as ********

Network requests

  • Secrets are only used locally during tool execution
  • They're never transmitted over the network except as part of tool execution (e.g., if a Bash tool runs curl -H "Authorization: Bearer {{vault:token}}", the secret is used in the curl command itself)

How the Vault Works

Storage Architecture

When you save a secret in Fleet:

  1. User input — You enter the secret name and value in Fleet's UI
  2. Keychain storage — Fleet calls macOS Keychain APIs to store the secret:
    security add-generic-password -s familiar -a vault-secret-YOUR_NAME -w YOUR_VALUE
  3. Encryption — macOS Keychain encrypts the secret using:
    • AES-256-GCM encryption
    • Keys derived from your user account password
    • Hardware-backed key storage (on Macs with T2 or Apple Silicon chips)

Secret Usage Flow

When an agent needs to use a secret:

  1. AI generates tool call — The AI model (Claude, OpenAI, etc.) generates a tool call with a placeholder:

    {"tool": "bash", "args": {"command": "curl -H 'Authorization: Bearer {{vault:github_token}}'"}}

  2. Fleet receives tool call — The Fleet backend receives this tool call from the AI provider

  3. Secret replacement — Fleet scans the tool arguments for {{vault:NAME}} patterns and replaces them:

    security find-generic-password -s familiar -a vault-secret-github_token -w

    The command becomes: curl -H 'Authorization: Bearer ghp_abc123def456...'

  4. Tool execution — The tool executes with the real secret value

  5. Output masking — Before returning the tool result:

    • Fleet retrieves all secrets that were used
    • Scans the output for any occurrence of secret values
    • Replaces secret values with ********
    • Returns the masked output

  6. AI receives masked result — The AI only sees the masked output, never the actual secret

Critical security property: The AI model never sees the secret value at any point. It generates tool calls with placeholders, and receives masked outputs.

Security Guarantees

What Fleet Guarantees

✅ Secrets never sent to AI providers

  • Secret replacement happens after the AI generates tool calls
  • Only placeholder names are sent to Claude, OpenAI, etc.

✅ Secrets never in conversation history

  • All tool outputs are masked before storage
  • Export/backup of conversations contains masked values only

✅ Secrets never in logs

  • Tool execution logs mask all secret values
  • Debug output automatically redacts secrets

✅ Secrets encrypted at rest

  • macOS Keychain uses AES-256-GCM encryption
  • Hardware-backed encryption on modern Macs

✅ User-scoped access control

  • Only your macOS user account can decrypt secrets
  • Other users on the same Mac cannot access your vault

What Fleet Cannot Guarantee

⚠️ Secrets used in tool execution may be observable

  • If a tool writes a secret to a file, that file will contain the secret
  • If a tool sends a secret over the network, it travels in the request
  • Fleet masks tool outputs, but cannot control what tools do with secrets

⚠️ Process memory may contain secrets

  • While tools execute, secrets exist in process memory
  • A privileged process (like a debugger) could read memory

⚠️ Keychain backup security depends on macOS

  • Time Machine backups include encrypted Keychain items
  • Security depends on backup encryption settings

Privacy Guarantee

When you use the vault, your AI provider never sees your secrets. Here's the data flow:

What goes to your AI provider:

  • Tool calls with placeholder syntax: {{vault:SECRET_NAME}}
  • Tool outputs with secrets masked: Response: ********
  • Conversation context (your messages, agent responses)

What stays on your machine:

  • Actual secret values (stored in Keychain)
  • Unmasked tool outputs (briefly, during execution)
  • Vault secret names (stored in Fleet's database)

Creating & Managing Secrets

Create a Secret:

  1. Open Settings (Cmd+,)
  2. Go to Security → Secure Vault
  3. Click Add Secret or Add a Secret
  4. Enter a unique name (e.g., github_token, openai_api_key)
  5. Enter the secret value (API key, password, token, etc.)
  6. Click Save

Use a Secret in an Agent: Ask your agent to use a secret by name. For example:

  • "Use the GitHub token from the vault to create a PR"
  • "Deploy using the AWS credentials from the vault"

The agent will reference it as {{vault:github_token}} or {{vault:aws_credentials}} when making tool calls.

View Secrets: In Settings → Security → Secure Vault, you can see all stored secret names (but not their values).

Delete a Secret:

  1. Open Settings → Security → Secure Vault
  2. Find the secret you want to remove
  3. Click the delete button
  4. Confirm

Using Secrets in Triggers

You can also reference vault secrets in trigger scripts using the same syntax:

#!/bin/bash
curl -H "Authorization: Bearer {{vault:github_token}}" \
  https://api.github.com/user/repos

When the trigger runs, Fleet replaces {{vault:github_token}} with the actual value.

Vault Tools for Agents

Agents can interact with the vault programmatically:

List Secrets (vault_list)

  • Returns names of all stored secrets (not their values)
  • Agents use this to discover what credentials are available

Request User Input (vault_save)

  • Prompt the user to securely input a new secret
  • Useful when an agent needs credentials that don't exist yet
  • Example: An agent deploying an app might request AWS credentials if they're not stored

See Vault Tools for more details.