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 into the child process at spawn time. The parent process never holds them. Nothing is written to disk. When the process exits, the values are gone.

This is a stronger guarantee than a .env file, but weaker than the proxy — the child process does hold the values in its environment for the duration of the process. For AI agents specifically, prefer the SDK or proxy. For non-agent tools and frameworks that cannot be modified, agentsecrets env is the right path. See Proxy Injection vs env Injection for a full comparison.

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