Migrating from .env Files

If your current setup relies on .env files, this guide walks you through moving to AgentSecrets. You can run both in parallel during the transition and cut over when you are ready.

Why .env files are risky with AI agents

.env files are particularly dangerous when using AI agents. Since agents often have filesystem access, they can inadvertently read or leak your secrets if they are stored in plaintext on disk.

AgentSecrets eliminates all of these vectors by keeping the value out of the filesystem (in keychain-only mode), out of environment variables, and out of any accessible process context.

Importing your existing .env

# Confirm you are in the right project and environment
agentsecrets status

# Import from .env or .env.development
agentsecrets secrets push

This reads your .env file, encrypts each value locally, uploads the encrypted blobs to cloud, and writes to the OS keychain. After verifying with agentsecrets secrets list and agentsecrets secrets diff, you can delete the .env file.

Replacing dotenv calls with AgentSecrets

from dotenv import load_dotenv
import os
import requests

load_dotenv()

response = requests.get(
    "https://api.stripe.com/v1/balance",
    headers={"Authorization": f"Bearer {os.getenv('STRIPE_KEY')}"}
)

from agentsecrets import AgentSecrets

client = AgentSecrets()

response = client.call(
    "https://api.stripe.com/v1/balance",
    bearer="STRIPE_KEY"
)

Using agentsecrets env as a drop-in replacement

For tools and frameworks that read from environment variables at startup and cannot be modified to use the SDK or proxy, agentsecrets env is the closest drop-in:

# Before
node server.js

# After
agentsecrets env -- node server.js

Values are injected directly into child process memory at spawn time via the operating system execve interface. Nothing is written to disk, the parent shell session remains completely clean, and when the child process exits, all decrypted variables disappear from memory.

agentsecrets env provides a hardened zero-disk security boundary:

• Zero Disk Exposure: Completely eradicates .env files, protecting against filesystem-scanning malware and accidental git commits.
• Process & Shell Isolation: Variables are never exported into your terminal shell and cannot be read by sibling processes.
• Stream Redaction: Terminal output is intercepted in real time by MaskingWriter, masking raw, Base64, Hex, and URL-encoded secrets to [REDACTED].

For outbound HTTP API calls where your code does not need direct access to secret values, use the Credential Proxy. For databases, background workers, and tools that require native environment configuration, agentsecrets env is the production-grade standard. See Proxy vs Environment Injection for architectural guidance.

if you use makefile, the lowest-friction way to useagentsecrets env in a project is to define a RUN variable at the top of your Makefile and prefix commands with it. This way you type make dev and not agentsecrets env -- npm run dev.

RUN := agentsecrets env --
dev:
	$(RUN) npm run dev
test:
	$(RUN) npm test

Migration checklist