.env files and API keys

In the lesson “Claude Code Can Reach Your Keys”, Claude Code, Anthropic’s AI coding agent (an AI helper that reads files and runs commands in your project), opens one file. This page explains that file. No coding needed.

Projects and API keys

A project is a folder that holds a program’s scripts and files, kept together in one place.

Many projects need to sign in to another service to work, such as a payment service or an AI service. To do that, they use an API key (also called an authentication key): a password that lets a program sign in to another service.

Think of an API key like the key card for an office building. Whoever holds the card gets through the door. Stripe, a payment service, warns that anyone who gets your secret key can make charges or read customer data in your name.

Why the key doesn’t go in the code

To hard-code a key means to type the key itself into the program’s scripts.

Developers avoid this because code gets shared with teammates, copied to other computers, and uploaded to websites that store code. A key typed into the code travels with it. Stripe warns that people constantly scan public code for API keys, and that even private code can leak.

The Twelve-Factor App, a well-known guide to building programs, gives a simple test: could you publish all your code to the world right now without giving away any passwords? If the answer is no, a secret is in the wrong place.

What a .env file is

A .env file (said “dot env”) is a plain text file that sits in the project folder. Each line holds a name, an equals sign, and a value. Here is a small one with a fake key:

PAYMENT_API_KEY=fake-key-not-real-12345

PAYMENT_API_KEY is the name. Everything after the = is the value, the key itself.

The code never holds the key. It holds a placeholder: the name of the key, standing in for the real value. When the program starts, a popular helper called dotenv copies each line of .env into environment variables: named values the computer hands to a running program. The code then asks for a value by its name. In a JavaScript program, the line looks like this:

const key = process.env.PAYMENT_API_KEY;

In words: “make a box called key, and fill it with the value named PAYMENT_API_KEY.” The code can now be shared, and the key stays behind in .env.

The Twelve-Factor App recommends keeping settings that change from one place the program runs to the next, like keys, in environment variables instead of in the code. A .env file is a convenient way to fill them in on your own computer.

The key lives in .env; the code holds only its name. Anything in the folder can read the file, the agent included.Swipe sideways to see the whole diagram →

The catch: .env is still a readable file

A .env file keeps the key out of the code, but it is still an ordinary text file on your computer. Anything that can read files in that folder can read the key.

That includes an AI coding agent. In the lesson, the agent opens .env and reads the key while fixing an app, and it never asks. The agent’s permissions docs explain why: reading a file inside the project is on the list of actions that need no approval from you. And whatever the agent reads goes into its conversation with the AI model, which runs on Anthropic’s servers, so the key leaves your computer.

Caution

Moving a key into .env keeps it out of the code you share. It does not hide it from programs running on your computer, the agent included.

The lesson teaches two settings that close this gap, and you need both:

• A deny rule, Read(./.env), added to the deny list in the project’s settings file, .claude/settings.json. It tells the agent’s own file tools never to read that file. It also blocks simple shell commands like cat. The permissions docs warn that this rule doesn’t reach a script that opens the file by itself.
• The sandbox, a wall your computer’s operating system enforces around the commands the agent runs and every program they start. On its own, the wall still lets those programs read .env. Once it’s on, it copies your deny rule onto the wall, so the rule then blocks them too. See the sandbox guide for what it is and how to turn it on (on Windows, only inside WSL2).

Keep your keys safer

• Keep .env out of Git. Git is a tool that keeps the history of every change to a project’s files, and teams use it to share those files. A .gitignore file is a list, saved in the project folder, of files Git should leave out. Put .env on that list. The dotenv guide is direct about it: you should not save your .env file to Git. If the file was already saved before you added the rule, the rule alone won’t remove it. GitHub’s ignoring files page shows the command that makes Git forget the file. The key is still in Git’s saved history, so replace it (see below).
• Use a test key while you build. Some services, such as Stripe, give you test keys that work in a separate test area and can’t affect your live account. Stripe asks developers not to use live keys where a test key will do.
• Replace a key that leaked, right away. To rotate a key means to create a new one and switch the old one off. Stripe says to rotate an exposed key immediately, even if you aren’t sure anyone saw it. GitHub says the same: if a key ends up saved in Git, the first step is to revoke or rotate it.
• Don’t send keys in email or chat. Stripe advises sharing keys only through a secrets-management tool, a service built to store passwords safely, and never in emails or chat messages.