VaultOS
GitHubDownload
0.3 previewNow native. Rewritten in Rust.

Your agent doesn't need
to see your keys.

VaultOS is a local vault for project secrets. Your coding agent asks it for a key by name. VaultOS writes the value into the project or runs the command with it, and the chat only ever gets the name.

Download for macOSView source

v0.3.0-preview.4macOS 13+ and LinuxSigned and notarizedFree and open source, MIT

An illustration of a real session. Names and data are synthetic.

Why

A key in a chat is a key in a transcript.

To get work done, an agent ends up holding your secrets. You paste one into a prompt, it reads a .env, a failing command prints one. From there the value sits in places you don't manage and can't clean up.

How the agent gets a keyWith a .env and a chat: You paste it, or it reads the whole .envWith VaultOS: It asks the vault by project and key name
What comes back to the chatWith a .env and a chat: The valueWith VaultOS: The key names. Values go to the file or the process
Command outputWith a .env and a chat: Whatever the program printsWith VaultOS: Vault values masked before the agent sees them
What it can reachWith a .env and a chat: Every key in every file it can openWith VaultOS: Only the projects, folders and commands you approved
Record of useWith a .env and a chat: NoneWith VaultOS: A signed audit entry for every use of a value
A key in a commitWith a .env and a chat: Found later, by someone elseWith VaultOS: Stopped by the pre-commit scan

How it works

The agent asks by name. It gets the name back.

You enroll each agent yourself and decide what it can reach. Everything you didn't grant is refused, and an agent cannot widen its own access.

  1. Agentclaude-code
    Scopesreadinjectrunreveal
    ProjectsAcme Storefront
    Folders~/work/acme
    01

    You enroll the agent

    Give it a name, scopes, the projects it may use and the folders it may write to. It gets its own token.

  2. inject_secrets({
  project: "Acme Storefront",
  target_path: "./.env"
})
    02

    It asks for what it needs

    Over MCP, or from a shell with vaultos-agent. VaultOS checks the request against the grant before anything is read.

  3. {
  "keys": [
    "STRIPE_SECRET_KEY",
    "WEBHOOK_SECRET"
  ],
  "refused": []
}
    03

    The work gets done without the value

    The keys land in the project or in the command's environment. The reply carries names, and command output comes back masked.

  • readList and search names and metadata
  • injectWrite approved keys into approved folders
  • runStart a command you allowed, get masked output
  • addCreate records that wait for your approval
  • revealReturn raw values. Off unless you grant it

Features

Made for secrets that live next to code.

API keys, environment files and SSH keys come first. The rest of a password manager is there when you need it.

Run a command with secrets. Write nothing to disk.

vaultos run starts any program with a project's values in its environment and masks them in the output. No .env to leave behind, and nothing for an agent to open afterwards.

  • Agents with the run scope can start only commands you listed
  • Values exist in the process, not in the repository

Catch a leaked key before it becomes a commit.

vaultos scan looks for your vault's own values in files, staged changes and Git history. As a pre-commit hook it stops the commit, whether you wrote the line or your agent did.

  • Matches your real values, not guesses from patterns
  • Reports the file and the key name, never the value

SSH keys that stay in the vault.

A built-in SSH agent serves your keys to ssh and Git and signs your commits. The private key is never written to ~/.ssh, and each new program that wants a signature is named and confirmed with Touch ID.

  • Agents can ask for time-boxed access that you confirm
  • Every signature is in the audit log
  • Touch IDUnlock and approve with a fingerprint, backed by the Secure Enclave.
  • Quick AccessSearch every project and copy a value from anywhere with ⇧⌘Space.
  • TemplatesCommit config files that hold vault:// references instead of values.
  • Sync you ownMac and Linux through your own private Git repository, encrypted and signed.
  • Autofill and passkeysChromium browsers and Safari. Fills only on the site a login was saved for.
  • A full vaultLogins, one-time codes, attachments, history, Trash and import from 1Password or Bitwarden.
The VaultOS window listing three projects.
A project's keys, each with Reveal, Copy, Edit and Delegate.
Agent settings: one enrolled agent with read, inject and run scopes.
The app in 0.3, with synthetic data.

Security

Local, encrypted, and clear about its limits.

No account and no server. The vault is a file on your machine, the core is Rust, and every use of a value by an agent is written to a signed, hash-chained log.

  1. Master passwordAccount Unlock Key

    Argon2id. Optionally combined with a Secret Key that never leaves your devices.

  2. wrapsVault Key

    Random, 256-bit. Changing your password re-wraps it and nothing else.

  3. wrapsProject keys

    One per project, so access and sync stay scoped.

  4. sealsItems

    XChaCha20-Poly1305, bound to their vault, project, item and revision.

What protects you

  • Agents reach the vault over a private Unix socket that accepts only your user. A browser cannot connect to it.
  • Secrets stay sealed in memory until they are used. Copies are marked concealed and cleared after 30 seconds.
  • Sync files are encrypted to your devices and signed. Tampered, replayed or unsigned files stop a pull.
  • Releases carry checksums, an SBOM and signed build provenance.

What it does not do

  • It has not been independently audited. This is a preview.
  • It cannot protect an unlocked vault from software running as you, or from a compromised OS.
  • It cannot stop an agent from reading a file it was allowed to write secrets into. Use run to avoid the file.
  • There is no account recovery. Lose the password and the backups, and the vault is gone.
Read the security model

Setup

Three steps to a connected agent.

About five minutes by hand. Or copy the prompt below and let your agent do the install while you handle the unlock.

  1. 01

    Install the app

    Download VaultOS, move it to Applications and create a vault with a master password. Add your first project and keys, or import a .env.

    Get v0.3.0-preview.4
  2. 02

    Enroll your agent

    In Settings → Agents, add an agent and pick its scopes, projects and folders. Start with read and inject on one project. VaultOS saves its token to a private file.

  3. 03

    Point your MCP client at it

    The bridge ships inside the app, so there is nothing else to install. Add it to your client's MCP config and ask the agent to run whoami.

mcp config
{
  "mcpServers": {
    "vaultos": {
      "command": "/Applications/VaultOS.app/Contents/Helpers/vaultos-mcp",
      "env": {
        "VAULTOS_AGENT_TOKEN_FILE": "/absolute/private/folder/agent-token"
      }
    }
  }
}
Or hand this to your agent

Help me install and connect VaultOS, the open-source vault for project secrets. Repository: https://github.com/KRNL-Studio/vaultos First read AGENTS.md and skills/vaultos/SKILL.md, including the setup reference. Follow the instructions for the current release and my MCP client. Check my machine and any existing installation before making changes. Preserve my current vaults, apps, Keychain entries and unrelated client settings. Use test credentials for the first check. Do not disable Gatekeeper or strip quarantine. The MCP bridge ships inside the app (VaultOS.app/Contents/Helpers/vaultos-mcp), so no Node.js is needed. I will unlock the app and enroll this agent myself. Start with read and inject access only to the project and output folder I choose. Keep reveal off. Never ask me to paste my master password or agent token into chat. Use a private token file outside source control. Connect the bridge, verify whoami and the approved projects, and test injecting one disposable key into a new Git-ignored file. Do not read or print injected values. Report what changed and any step left for me. Do not enable background access, migrate data, configure sync or widen grants unless I ask.

FAQ

Questions

Can an agent still read my secrets?

If it has shell or filesystem access to a file that contains them, yes. VaultOS keeps values out of tool responses and masks them in command output, but it cannot stop an agent from reading an .env file it can already open. To avoid the file altogether, use run: the command gets the values in its environment and the agent gets masked output. Revealing a raw value is a separate scope, off by default.

Has it been audited?

No. VaultOS is a preview and has not had an independent security audit. The threat model, the cryptography and the known limits are written down in the repository, with fuzz targets and test vectors. Start with test credentials and keep your own backups.

Is the macOS build signed?

Yes. The macOS build is signed with a Developer ID and notarized by Apple, so it opens like any other app. Each download also has a checksum and signed build provenance you can verify.

Which coding agents work with it?

Any client that runs a local MCP server over stdio. Agents that only have a shell can use the vaultos-agent command instead. Both ship inside the app and need no Node.js or other runtime.

What happens when I close or lock the app?

Closing the window locks the vault and leaves VaultOS in the menu bar. Lock, screen lock, sleep and 15 idle minutes lock it fully, and agents get a clear "locked" answer. Background access, so agents keep working with the window closed, is off until you turn it on.

Do I need an account or a server?

No. The vault is a file on your machine. Sync is optional and goes through a private Git repository you own, encrypted and signed end to end. There is no reset service: keep your master password, your Emergency Kit if you use a Secret Key, and backups.

I use 0.2. How do I upgrade?

Open your vault in 0.3 and choose Upgrade this vault. The upgrade is one-way and keeps the old file as a backup. Sync from 0.2 does not carry over, so start a new sync repository, and point your MCP client at the bridge inside the app.

Stop pasting keys into chats.

Free, open source, and it runs entirely on your machine.

Download for macOSLinux and source builds