Abstract
Automic Vault narrows local authority. It does not make agents safe.
Automic Vault is strongest when the risk is ambient local authority: plaintext tokens in .env, ~/.aws/credentials, ~/.npmrc, GitHub CLI state, MCP configuration, or other files that an agent can read before a human notices.
It stores supported secrets in the macOS keychain, exposes them through native credential-helper protocols where a tool supports that boundary, asks before injecting named values into an executable, and can run an agent through a synthetic toolchain where host tool execution is mediated by the local app.
Automic Vault removes several high-value ambient privileges and makes sensitive local authority harder to spend silently. It is not same-user malware containment, a root-compromise defense, a cloud policy engine, or a proof that an approved tool is safe.
The credential-helper adapter system is the strongest version of the secret boundary. Instead of leaving a token in a config file or passing it as a broad environment variable, a migrated tool can keep only a non-secret helper reference on disk. The tool then asks av credential-helper for a credential through the protocol it already understands, such as AWS credential_process, Kubernetes ExecCredential, Cargo credential providers, Docker-compatible registry credential helpers for Podman and Skopeo, or WakaTime's api_key_vault_cmd.
Threat model
The attacker is often an agent with normal local access.
Automic Vault assumes a local AI coding agent can read project files, inspect common developer configuration, invoke command-line tools, and cause sensitive strings to appear in transcripts, logs, patches, or tool output.
- Plaintext developer secrets visible to an agent.
- Risky command execution by local tools.
- Compromised or misleading package tooling.
- Prompt injection that tells an agent to use existing credentials.
- Root, kernel, hypervisor, or physical-device compromise.
- Same-user malware deliberately modifying local approval state.
- Cloud-side compromise after a credential is legitimately used.
- A user pasting raw secrets into model context.
Architecture
The security boundary is local, not hosted.
The public website is static product information and download metadata. It is not a hosted vault, account system, or remote policy engine. The runtime boundary lives on the Mac.
| Component | Security role |
|---|---|
| Automic Vault.app | Shows package dossiers, approval prompts, helper operations, and containment logs. |
av | Runs package operations, scanning, secret save/inject, containment, tracing, approval gates, and credential-helper adapters. |
| nuke-helper | Performs root-required package, isotope, helper, and always-allow operations. |
| macOS Keychain | Stores named CLI secrets under the Automic Vault isotope service. |
| Credential helpers | Let selected tools request keychain-backed credentials at runtime through native authentication protocols. |
| Local state | Approval requests and decisions live under ~/Library/Application Support/Automic Vault/. |
| Package roots | Release builds use /opt with stubs in /usr/local/bin; debug builds use /tmp roots. |
Methods
Controls are concrete: paths, keys, executables, and approvals.
Secret storage
av save KEY stores a trimmed value in the macOS keychain. Key names are restricted to ASCII identifier-like names, and empty keys or empty trimmed values are rejected. New keychain items attach a trusted-application ACL that includes the current app context and /usr/local/bin/av when that command exists.
The caveat: this uses macOS keychain protection rather than a custom cryptosystem. Once a secret is loaded for injection, it exists in process memory. Once injected, it exists in the approved process environment.
Secret injection
av inject +KEY /absolute/path/to/tool resolves and opens the target, validates the target and parent directories, asks for approval when needed, and executes the target with selected environment variables added.
- The target path must be absolute.
av injectrefuses to run as root.- Core dumps are disabled before key loading.
- Existing environment values are preserved unless
--replace-existing-envis used. - The opened file descriptor is compared with the path immediately before
execve. - Loaded credential strings are zeroed on failure paths before being dropped.
Credential-helper adapters
av credential-helper <protocol> is the stronger path for tools that already know how to ask a helper for credentials. Instead of reconstructing a plaintext config file or injecting a broad environment variable, Automic Vault can rewrite the persisted tool config to a non-secret helper reference and provide the credential only when the approved tool invokes the helper.
This matters because the agent can inspect the project and many home-directory files without seeing the secret. It sees a helper command or protocol reference, not the token itself. The credential crosses the boundary only at the moment the tool performs the authenticated operation.
Current adapters include AWS credential_process, Kubernetes ExecCredential, Cargo's credential provider protocol, NuGet credential provider flows, Terraform and OpenTofu credential helpers, Docker-compatible registry helpers for Podman and Skopeo, and WakaTime's api_key_vault_cmd.
The helpers are not general-purpose secret printers. The dispatcher disables core dumps before helper execution. The generated wrapper passes a per-run approval token through AUTOMIC_VAULT_CREDENTIAL_HELPER_TOKEN, and helpers validate that token before returning credentials. Helpers also check that their parent process is the expected Automic Vault-managed launcher, and where the tool boundary allows it, validate that the parent path is root-controlled.
The caveat: credential helpers are still a local process boundary, not a cryptographic proof that the whole system is safe. A legitimately approved tool can receive and use the credential. Same-user malware and root compromise are still outside the current model. Helper coverage is also package-specific: it is excellent where the upstream tool has a native protocol, and absent where no adapter has been built yet.
Always-allow rules
Durable approval is intentionally narrower than "remember this prompt." It is available for root-owned, non-writable executables reached through non-writable parent directories. For script interpreters, the script path is part of the scope. Root-owned scripts can be remembered by path; non-root scripts require path plus SHA-256 hash. env shebangs and launchers are not eligible.
Command approval
Approval requests include the command, current directory, parent or requesting process, agent id where available, and environment key names. Decisions are matched by request id and cleared after use. This is good for accidental agent overreach and many compromised-tool cases, but it is not a cryptographic authorization service against a same-user malicious process.
Containment
av contain creates a temporary toolchain, replaces PATH with generated stubs, starts the initial command through sandbox-exec, and routes host tool execution to the local vault daemon for approval.
The current sandbox profile is best understood as execution mediation. It denies unapproved child process execution, but it is not a strong file-read sandbox, network sandbox, or full macOS application container.
Package roots and metadata
Nucleus installs supported packages under predictable roots and exposes command stubs through predictable paths. Package catalog data, isotope metadata, radioisotope detectors, and security recommendations let the app explain package-specific risk.
The gap is supply-chain trust. Automic Vault reduces local credential exposure and can harden specific tools, but it is not yet a universal provenance system for every upstream package, bottle, tarball, wheel, or npm artifact.
Privileged helper
The GUI uses Apple's privileged-helper flow for root-required operations, asks for device-owner authentication before privileged operations, and checks helper identifier, team identifier, and helper version when deciding whether blessing is needed. The helper verifies its own expected code-signing identity at startup and again for privileged commands.
The caveat: the helper should not yet be described as a complete per-client authorization firewall for every method. Future hardening should make caller identity checks explicit in the helper service itself.
Successes
The strongest choices move decisions below the prompt layer.
Controls happen where local tools run, not only where prompts are written.
Supported secrets move from plaintext files into keychain-backed storage.
Tools that support credential-helper protocols can request secrets at runtime without restoring agent-readable plaintext config.
Prompts show concrete paths, commands, parent processes, requested keys, and root-control status.
Always-allow is tied to root-controlled or hash-bound execution boundaries.
Release install paths and package metadata endpoints are fixed rather than arbitrary runtime knobs.
The project does not claim that agents become safe just because a local tool is installed.
Holes and caveats
The current limits should be stated plainly.
- Same-user malware is not contained. A malicious process running as the same user is outside the current approval-file and socket trust model.
- Root compromise wins. Root can read or modify package roots, helper state, approval records, and process memory.
- Approved tools can leak. A secret injected into an executable is available to that process and may be available to children it spawns.
- Environment variables are a leaky transport. They are convenient for CLIs, but not the best long-term secret delivery mechanism. Credential helpers reduce this exposure for supported tools, but do not remove the underlying need to trust the approved tool.
- Containment is partial. Today it mediates process execution more than file, network, or syscall behavior.
- Scanner coverage is incomplete. New tools, custom configs, and unusual paths can be missed.
- Package provenance is not universal. Upstream package integrity still depends heavily on package ecosystems unless package-specific hardening exists.
- Approval fatigue is real. If prompts become too broad or frequent, users will approve mechanically.
- No formal public third-party audit is documented. External review should follow once the core boundary stabilizes.
Hardening roadmap
The next work should strengthen local authorization and provenance.
- Authenticate local approval channels more strongly than writable per-user files.
- Add explicit helper-side client identity and authorization checks for every privileged method.
- Expand credential-helper adapters and reduce environment-variable secret transport for tools that can support file descriptors, keychain callbacks, native helper protocols, or scoped IPC.
- Expand containment from process-exec mediation toward more granular file and network policy where macOS allows it.
- Sign and verify package/security metadata with rollback protection.
- Add more package-specific isotopes, detectors, and approval manifests for high-risk developer tools.
- Publish a formal external security review when the core boundary stabilizes.
Automic Vault is worth using because it removes high-value ambient privileges from agent runs. The remaining work is to make the local coordination channels and package provenance model as strong as the secret boundary wants to be.
Implementation anchors