EnvVault: A Lightweight Secret Launcher for Secure Local AI Development

The rise of AI agents operating on local codebases has turned a once‑benign habit—storing API keys directly in .env files—into a potential liability. When an agent can read or modify your repository, any plaintext secret tucked into environment variables becomes as exposed as handing over your workstation to a stranger. Even if the agent itself is trustworthy, accidental logging, screenshots, or copy‑paste can leak credentials into shared spaces, undermining the very isolation that local development promises. This shift has prompted developers to rethink how secrets are handled during iterative, agent‑assisted workflows, especially when the goal is to keep the repository itself free of raw credentials while still providing the runtime with the keys it needs.

Existing secret‑management tools such as 1Password CLI, Infisical, direnv, dotenv‑based loaders, and chamber already address the problem of keeping secrets out of source control. Each offers a robust vault, policy engine, or injection mechanism, but they often come with overhead that feels disproportionate for a solo developer or a small team working on a laptop. Setting up a remote secret server, managing access tokens, or learning a new CLI syntax can slow down the rapid feedback loops that local development thrives on. Consequently, many practitioners look for a solution that is both lightweight and tightly integrated with the operating system’s native credential storage, without requiring a separate server or complex configuration.

EnvVault was created to fill that niche: a minimal, local‑first secret launcher that treats the OS credential store as the source of truth while keeping only references in the project’s .env file. Instead of duplicating secrets across multiple tools, EnvVault stores the actual values in macOS Keychain (or, via go‑keyring, in the credential stores of Windows and Linux) and resolves references like envvault://openai/dev at launch time. The resolved value is injected directly into the child process’s environment, ensuring that the repository never contains raw keys, yet the application receives exactly what it expects. This approach marries the simplicity of a dotenv file with the security of a system‑backed vault.

In its default mode, EnvVault employs a direct credential flow. When a developer runs envvault exec , the tool parses any variable whose value begins with envvault://, looks up the corresponding entry in the OS credential store, and copies the plain secret into the child’s environment under the expected variable name (for example, OPENAI_API_KEY). This mirrors the workflow offered by chamber but differs in two key ways: the secret resides in the native keychain rather than a separate vault file, and the .env contains only a reference, not the secret itself. Because the resolution happens just before the target process starts, there is no window where the secret is written to disk or logged inadvertently, reducing the attack surface associated with static .env files.

The direct credential flow offers compelling advantages for everyday local development. By leveraging the operating system’s credential store, EnvVault benefits from built‑in encryption, biometric gating (Touch ID or Windows Hello), and seamless backup mechanisms that many developers already trust. Unlike a dedicated secret server, there is no additional service to run, no network latency, and no need to manage API tokens for the vault itself. This makes the tool particularly attractive for macOS users who already rely on Keychain for passwords, certificates, and other secrets, allowing them to extend the same trust boundary to development API keys without leaving their familiar workflow.

Early iterations of EnvVault experimented with a localhost proxy mode, wherein the child process would receive a short‑lived, proxy‑specific token instead of the real API key. The proxy would inspect each outbound request, verify it against an allow‑list of methods and paths, then attach the actual credential before forwarding the request to the upstream service. While this approach can further reduce the exposure of the raw key—since the child never sees the true secret—it proved to be niche in practice. Many SDKs and HTTP libraries do not expose hooks for inserting a custom bearer token based on dynamic request inspection, limiting the scenarios where the proxy could be used without code changes.

Despite its reduced feature set, the proxy mode remains an intriguing option for specialized use cases. If an SDK or framework accepts a custom base URL and a bearer token—as is common with OpenAI‑compatible endpoints—EnvVault can generate a temporary token that is meaningful only to the local proxy. The proxy then consults the OS credential store, retrieves the real provider key, and attaches it to authorized requests. This split‑token model adds a layer of indirection that can thwart accidental logging of the proxy token, because the token itself is useless outside the proxy’s context. However, developers must verify that their target library permits overriding the base URL and token; otherwise, they must fall back to the direct credential flow.

Getting started with EnvVault is deliberately straightforward. On macOS, a single Homebrew command (brew install envvault) makes the binary available. After installation, developers can add credentials via the CLI (envvault credential add ) or through a lightweight browser‑based admin UI launched with envvault admin. The UI deliberately omits any display of stored values, reinforcing the principle that secrets should remain hidden even from the tool’s own interface. Once credentials are stored, the developer writes references in .env—for example, OPENAI_API_KEY=envvault://openai/dev—and launches the application with envvault exec . The tool resolves the reference, injects the real key, and the process runs as if the key had been placed directly in the environment.

For those who prefer to avoid a .env file altogether, EnvVault supports inline environment variable syntax. By placing a double dash (–) after the envvault exec command, everything that follows is treated as the child command, allowing statements like envvault exec — python script.py OPENAI_API_KEY=envvault://openai/dev. This pattern ensures that the parser knows where the EnvVault reference ends and the actual program arguments begin, preventing accidental injection of unintended variables. The inline approach is especially useful for quick experiments, one‑off scripts, or CI‑like scenarios where a temporary .env file would be overkill.

EnvVault’s design shines when paired with SDKs that read API keys straight from the process environment, such as the official Google Gemini SDK or many OpenAI‑compatible libraries. Because the direct credential flow places the real secret into the expected environment variable before the child process starts, the SDK behaves exactly as it would with a traditional .env entry—no code changes, no extra configuration, and no runtime overhead. This high degree of compatibility lowers the adoption barrier: developers can try EnvVault on an existing project, verify that the application still receives its keys, and then commit the updated .env containing only references, knowing that the repository is now free of raw secrets.

When proxy mode is viable, the workflow shifts slightly but remains developer‑friendly. After storing the provider credential, the developer runs envvault proxy create to generate a proxy definition, which outputs a ready‑to‑copy .env snippet containing variables like ENVVAULT_PROXY_URL and ENVVAULT_PROXY_TOKEN. The application is then configured to read these two variables instead of a direct API key. At runtime, EnvVault launches an ephemeral proxy on a random local port, validates each outbound request against the proxy’s allow‑list, and, if approved, retrieves the real key from the OS credential store to attach to the request before forwarding it upstream. The child process never sees the true secret, only a token that is meaningless outside the proxy’s context.

From a security standpoint, EnvVault’s guarantees are purposefully scoped. It ensures that repositories, .env files, command‑line histories, and standard output streams do not contain plaintext API keys, thereby reducing the likelihood of accidental exposure via Git commits, shared screenshots, or log aggregation systems. However, EnvVault does not attempt to sandbox the child process or prevent the secret from being read from memory once the process is running; if a malicious actor gains access to the running application, they could still extract the key from its environment. This limitation is intentional: the tool aims to shrink the “surface area” where secrets can leak, not to provide a full‑blown runtime isolation sandbox.

Fail‑closed behavior further reinforces safety: if EnvVault cannot resolve a reference—for example, because the credential has not been stored or the keychain is locked—it refuses to launch the child process altogether rather than falling back to any existing environment variable. This prevents a misconfiguration from silently leaking a fallback key that might be less privileged or, worse, a production secret. Developers receive a clear error message prompting them to add the missing credential or unlock their keychain, fostering a habit of explicit secret management rather than reliance on ambient variables.

Looking ahead, EnvVault’s roadmap remains modest, reflecting its origins as a personal tool. Potential enhancements include richer proxy policies (such as per‑credential rate limiting), first‑class support for multi‑project contexts, and a plugin system that would allow agents to automatically invoke envvault exec when they need to run a command. The agent‑focused “skill” already present in the repository demonstrates how an AI assistant can be taught to request secret‑protected executions, aligning the tool’s goals with the emerging paradigm of AI‑augmented development.

For teams and individual developers wrestling with the trade‑off between convenience and security, EnvVault offers a pragmatic middle step. If you are working primarily on macOS (or can adapt the go‑keyring backend for Windows/Linux), already trust your OS credential store, and want to keep your Git history free of raw API keys, give EnvVault a try. Install via Homebrew, populate your keychain with the needed secrets, replace the values in your .env with envvault:// references, and launch your workflows through envvault exec. Over time, monitor whether the reduced exposure aligns with your risk tolerance, and consider whether the proxy mode adds value for any specific services you use. By making the secret‑management step explicit and lightweight, EnvVault helps you develop with confidence that your credentials stay where they belong—out of the repository and under the control of your operating system’s secure storage.