Understanding API Keys and .env Files

What is an API Key?

An API key is like a password that lets your software talk to someone else's service. When you use an AI model (OpenAI, DeepSeek, Anthropic), a payment processor (Stripe), or a cloud service (Cloudflare), you authenticate with an API key instead of a username and password.

Think of it as a valet key for your account. It proves you're allowed to use the service, but it's scoped to specific things — it might only let the holder send chat messages (not change your billing), or only process payments (not read your customer data).

Step 1. The Two Types of Keys: Secret vs Publishable

Most services give you two kinds of keys. The distinction is critical:

• •Secret key (or private key) — starts with prefixes like sk-, whsec_, or sk_live_. This is your full-access credential. Anyone with this key can spend your money or access your data. Never share it, never commit it to git, never put it in frontend code. It goes in your .env file on the server.
• •Publishable key (or public key) — starts with prefixes like pk- or pk_live_. This is safe to put in frontend JavaScript or share. It has limited permissions — it can initiate a payment or identify your account, but it can't actually charge money or read secrets.

Key prefixes by service:

Rule of thumb: if the key starts with sk_, it's a secret. If it starts with pk_, it's safe for browsers. When in doubt, treat it as secret.

Step 2. What is a .env File?

A .env file is a simple text file that stores your secret keys and configuration values as plain text. It's the standard way to keep secrets out of your code.

Here's what one looks like:

The format is simple:

• •One KEY=VALUE pair per line.
• •No spaces around the = sign.
• •No quotes needed for simple values (use quotes if the value contains spaces or special characters).
• •Lines starting with # are comments.

Step 3. Why Not Put Keys in Code?

Putting API keys directly in your code is the most common security mistake developers make. Here's why it's dangerous:

• •Git commits remember everything. If you accidentally commit a key and push to GitHub, bots will find it within minutes and drain your account. Deleting the commit isn't enough — you must revoke the key immediately.
• •Anyone who reads your code gets your keys. If you share code, send it to a client, or put it on a public repo, your secrets go with it.
• •Different environments need different keys. Your development setup should use test keys (Stripe "test mode," for example). Production uses live keys. The .env file makes this swapping trivial.

The .env file solves all of this: add .env to your .gitignore file so Git never tracks it, and keep a separate .env.example file (with placeholder values) so collaborators know which keys they need — without seeing yours.

Step 4. Where Different Tools Look for .env

• •Hermes Agent — ~/.hermes/.env (your home directory's .hermes folder). Add keys like DEEPSEEK_API_KEY=sk-... or OPENAI_API_KEY=sk-....
• •Docker & Docker Compose — use an .env file in the same directory as your docker-compose.yml, or pass them with environment: in the compose file.
• •Python projects — put .env in your project root and use the python-dotenv library to load it.
• •Node.js projects — put .env in your project root and use the dotenv package.
• •Systemd services — use EnvironmentFile= in your service definition.

Step 5. Security Checklist

• 1.Add .env to .gitignore — do this before your first commit. If you've already committed a secret key, revoke it immediately (go to the service's dashboard and generate a new one) — don't just delete the file.
• 2.Use .env.example as a template — create a copy called .env.example with placeholder values (e.g., DEEPSEEK_API_KEY=your-key-here). Commit this file — it tells collaborators what keys they need without exposing real ones.
• 3.Use different keys for different environments — Stripe has "test mode" keys (starting with sk_test_) that generate fake charges. Use those in development. Only put live keys on the production server.
• 4.Limit key permissions — most services let you restrict what a key can do. If you only need to send chat messages, don't create a key with billing access. Create a new scoped key instead.
• 5.Rotate keys periodically — every few months, generate a new key and retire the old one. It limits damage if a key was ever exposed without your knowledge.

Step 6. Common Mistakes to Avoid

• •Putting secrets in config.yaml instead of .env. Config files get shared and synced. Secrets files don't. Hermes Agent strictly separates these — config.yaml for settings, .env for secrets.
• •Using live keys during development. Always use test-mode keys (Stripe) or a separate dev project (OpenAI, DeepSeek) when building. One wrong command can cost real money with live keys.
• •Copy-pasting keys into chat or support tickets. If a service asks you to share a key for debugging, they mean the last 4 characters, not the whole thing. No legitimate support agent needs your full secret key.
• •Forgetting to set restrictive file permissions. On Linux/Mac, run chmod 600 .env so only your user can read the file. On shared servers, this is essential.