English · 简体中文

macOS protects your apps. We protect your command line.

Since I created Homebrew, Apple has transformed Mac app security. I’m bringing that same care to the command line.

— Max Howell

You install tools to do a job. Their credentials often sit in files or helpers that other code running as you can read. Agents inherit that access.

Automic Vault hardens supported CLI tools on macOS. AV understands how supported commands use credentials and classifies operations by sensitivity. Set Access Levels in advance for each app and Tool to reduce Approval prompts without blanket access. Unknown operations still require Approval.

We move exposed credentials into the Keychain and change how the tools request them. You keep your commands; AV checks the complete operation before applying a protected credential.

Download the latest release, or install with Homebrew:

brew install --cask automic-vault/isotopes/automic-vault
open /Applications/Automic\ Vault.app

Scan for exposed credentials, harden a supported Tool, then verify the result:

av scan   # or open the app
av harden gh
av doctor gh

Automic Vault continuously checks over 100 developer-tool configurations for Exposures and Hazards, including plaintext credentials, permissive Keychain items, and ambient credential helpers. Each Finding includes a mitigation.

Detectors inspect without changing your environment or requesting Secrets. A clean Scan means no supported Detector found an issue; it cannot certify that your machine is holistically secure.

Detection coverage and interpreting Findings

Hardeners move supported credentials into Secret Custody in the macOS Data Protection Keychain and configure the Tool's Authorization Gate. Depending on the Tool, this can mean a credential helper, wrapper, or Isotope: an Automic Vault-compatible build of the Tool.

av doctor verifies the protection Automic Vault installed.

Hardening, verification, and AWS/Docker handoffs

Automic Vault checks the Verified Launcher, Tool, Target, command, arguments, working directory, Secret Names, and selected Value sources before allowing the complete operation on the Mac where it will run.

With Read Only access, one GitHub token produces three decisions:

gh issue list     → automically authorized
gh issue create   → Approval required
gh auth token     → Secret Disclosure; Approval required

Each gate applies a default Access Level or a rule for the Verified Launcher. Write Access permits recognized reads and writes; disclosure and elevated credential use still need Approval. Unknown operations need Approval at every Access Level.

Automic Vault controls the handoff. The Target controls the Secret after receiving it.

Access Levels, Approval, and locked-device behavior

By default, the nearest Verified Launcher with an explicit Access Level supplies policy. Terminal's Write Access does not override an agent's Read Only rule. For a harness that should supply policy for the Launchers it starts, enable Override descendant Launcher rules on its rule at that gate, then review and approve the change. The outermost eligible override wins; explicit Deny and runtime requirements still apply.

The option defaults off. Turning it off or removing an enabled rule also requires Approval, because doing so can expose broader access in a child rule.

Examples, setup, and SSH policy boundaries

An eligible Codex task or Claude Code session can request Allow Write Access for 10 Minutes…. The in-memory grant covers one Verified Launcher, Tool-specific gate, and agent task. A visible strip lets you add ten minutes, suspend access and its countdown, or end the grant.

The task identifier is a forgeable narrowing label; the Verified Launcher remains the identity boundary. Grants exclude direct Secret access, Secret mutations, elevated credential use, disclosure, and unknown operations.

Grant scope, expiry, and controls

Require Touch ID on your Mac for an allow action. Each Approval uses a fresh biometric result for that exact request, without a password, Apple Watch, or pointer-driven fallback. Touch ID requires an active Mac session and awake displays, and can coexist with iPhone Approval.

Enable Touch ID Approval

Approve operations across your enrolled Macs from eligible iPhones on the same iCloud Keychain account. Each Mac keeps its Secrets, policy, enforcement, and Authorization History local; the iPhone never receives Secret Values.

Enabling iPhone Approval removes pointer- and keyboard-driven allow actions from that Mac. Separately enabled Touch ID Approval can still carry an Approval.

Enrollment, notifications, and account-wide recovery · Join the public iPhone beta on TestFlight

Inspect allowed and denied requests, the operations and software involved, and the decision source. Automic Vault persists and verifies an allowed Secret Use's record before releasing the Secret; recording failure denies release.

$ av history
$ av history --since 7d --json

Each read requires Approval unless you grant that exact Verified Launcher Authorization History Access in Settings. This is a separate setting from av list's Secret Name Access. An unverifiable Launcher cannot use that grant and needs Approval. The read itself appears in the returned history.

History is local, stored as encrypted rows in one SQLite file with its key in the Data Protection Keychain. Records are available for up to 30 days. Settings lets you choose an encrypted payload retention target from 1–1024 MiB (default 25 MiB); usage can exceed it between periodic cleanup passes. SQLite overhead is additional. --since returns every retained record in the window. Terminal tables use a pager; --no-pager, --json, and redirected output bypass it. History is not tamper-proof or a complete forensic log.

Authorization History and its limits

Choose which terminals, IDEs, agents, or eligible standalone CLIs receive authority. Automic Vault checks the live Launcher's code identity and runtime protections on each request. Launcher-specific policy names that exact identity.

Code signing proves identity and integrity, not intent. A failed identity or runtime check blocks automic authorization. Prefer vendor-signed distributions when available; signing an interpreter does not authenticate the scripts, dependencies, or plug-ins it loads.

Launcher eligibility and vendor-signed Tools

For an unsigned single-file Mach-O CLI, Automic Vault can snapshot the executable into a signed Launcher Bundle with Hardened Runtime and a root-owned command link. Each authorization revalidates its enrolled generation, payload, signatures, and runtime posture. Changes or re-signing hard-deny its requests.

A Launcher Bundle establishes identity for that packaged code. It cannot establish publisher trust or make the CLI safe. Scripts and directory-shaped Tools are unsupported.

Create and update a Launcher Bundle

Save a secret:

$ av save API_TOKEN   # prompts via stdin

Save a project secret:

$ av save --project-directory=. API_TOKEN

Automic Vault selects the nearest Project Value at or above the physical working directory, falling back to the Global Value when none matches. A read failure for the selected Value ends the request without trying another value.

The directory selects a Value and grants no authority. The same name-based policy covers all Values of that Secret.

• Project Values, dotenvx, and mise
• Varlock

$ av save --multiline DEPLOY_PRIVATE_KEY
# Hidden input; Ctrl-D finishes after the final newline.
$ av save --stdin API_TOKEN <&3
# Read exact bytes from an existing descriptor until EOF.

Both modes require Approval. --stdin preserves whitespace and newlines; Values must be nonempty UTF-8 without NUL bytes, at most 1 MiB.

Input modes · Copy selected v1 Secrets

You can inject secrets into anything:

av inject +SECRET_NAME -- /path/to/something   # shows an approval window

For reduced exposure†, we support injecting via file descriptors instead of environment variables:

$ av inject --mode=fd +FOO:3 +BAR:4 -- /path/to/something

Each Secret arrives through its own anonymous pipe as exact stored bytes, followed by EOF. Automic Vault removes the requested names from the Target's environment and requires fresh Approval for every invocation. Descriptors must be unused, and each Value must fit the available pipe buffer.

FD delivery and its limits

† Environment variables both spread to child processes and allow any part of large codebases to read them.

Direct injection can be automatically authorized for a Verified Launcher. We do not recommend this: we recommend using blessed scripts.

Review a script once and bind its canonical path, exact contents, declaration, and capabilities to a Blessing:

$ av bless ./path/to/script

The script declares the Secrets and Tool capabilities it needs:

#!/usr/local/bin/av inject +DEPLOY_TOKEN -- /bin/bash
# --- automic-vault
# capabilities:
#   gh: read-only
#   aws: write
# ---

For compatibility, omitting the manifest inherits automic authority already available from the calling context. Make that choice explicit with:

# --- automic-vault
# capabilities: { inherit: true }
# ---

Use an empty declaration to ensure every later gated operation requires Approval while Automic Vault can attribute it to the live script execution, regardless of which Launcher calls the script:

# --- automic-vault
# capabilities: {}
# ---

The Secret Names in the av inject shebang are authorized separately. A script with no Secret Names and capabilities: {} starts without Approval because it receives no Automic Vault authority. This is an authorization ceiling, not a sandbox: ordinary commands still run with the user's normal operating-system permissions. Restarting Automic Vault or losing observable ancestry ends the memory-only ceiling, just as it ends active Blessed Script state.

Compatibility debts reserved for the next major version are tracked in Future Breaking Changes.

Editing the script or declaration invalidates the Blessing. A Launcher Endorsement lets one Verified Launcher automically authorize that exact Blessing. Use Blessed Scripts for reviewed work that exits, and Tool Authorization Gates for long-running processes.

FD delivery currently requires fresh Approval, including when invoked inside a Blessed Script. FD mode in an av inject shebang is unsupported.

Blessings and execution guarantees · Running scripts across app restarts

A reentrant Blessed Script does deterministic work until it needs agent input, then prints a prompt and exits. The prompt names the required output, fixed subcommands that expose reviewed capabilities, and the command to continue.

Automic Vault authorizes every invocation separately. Keep Secret Values within the script's execution and validate agent output before using it.

Release example with GitHub, S3, and CloudFront includes input validation, digest checks, conditional writes, and idempotent retries.

Sign Git commits and tags without giving Git the private key or passphrase. The GPG Signing Gate authorizes private-key use while your normal Git commands keep working. You can select a separate signing credential for exact Verified Launchers so agents use a distinct signing identity.

The gate offers Approval Required, Allow Signing, and Deny. The signing Target handles the private key while creating the signature.

Configure Git signing

Give each SSH key its own Default Policy and Verified Launcher rules. You can allow an agent to authenticate with a GitHub key while requiring Approval for a separate homelab key. New keys start at Approval Required; the original key keeps its existing policy.

SSH clients receive signatures, never the private key. Allow Authentication can permit remote writes. A key's name does not restrict destinations: any service accepting that key remains reachable with its authentication authority.

Configure the SSH agent and per-key policies

AV's Secret Proxy gives your application a random, session-specific Secret Reference in place of each Secret Value:

$ av save API_TOKEN
$ av proxy +API_TOKEN -- node --use-env-proxy app.js

The proxy applies the real Secret when that reference appears in an approved outbound HTTP/S request. Starting a Proxy Session and adding a destination require Approval. Allow for Session remembers that origin and Secret Name only for the session.

The application must support the supplied proxy and scoped CA settings. Secret References and the Proxy Credential are bearer values: code that obtains them can use destinations already allowed for that session.

Application example, .env, and compatibility

The Varlock integration resolves Secrets through ENV and can compose with Varlock's own credential proxy. It requires one Approval per run and does not support Automic Authorization or Blessings. Varlock's proxy and av proxy are separate sessions; don't nest them.

Automic Vault protects against untrusted or compromised code running with your normal user privileges. It builds on macOS code signing, the Data Protection Keychain, TCC, Hardened Runtime, and live process identity.

Root or kernel compromise, arbitrary local destruction, and a Target's behavior after receiving a Secret remain outside the product boundary. Wrappers cannot intercept every process execution. Keep your terminal and agent harness's macOS permissions minimal.

Network filtering and general-purpose agent sandboxing are outside Automic Vault's scope and roadmap. These apps cover those needs:

• Tiny Shield monitors your Mac's network connections and lets you block apps or domains. Automic Vault controls whether an operation may use a protected credential; Tiny Shield adds control over where apps can connect, including traffic that uses no credential.
• agentsh applies file, network, and process policies to agents run through it. Use it to restrict workspace access and command execution alongside Automic Vault's Secret Custody and Authorization Gates. Those restrictions address local actions, such as deleting files, that need no protected Secret and may never reach an Automic Vault gate.

• User manual
• Documentation index
• Choosing a Mechanism
• Domain language, architecture, and positioning
• Architecture decisions
• Homebrew tap
•