---
name: shipholm-env-and-secrets
description: "Set environment variables and secrets such as API keys for Shipholm apps – one at a time or from a .env file, for one app or all apps. Use when an app needs configuration or a key."
---

# Environment variables and secrets
Give apps configuration and API keys – for one app or for all apps of the account.

## Steps
- One value: `set_env(name="API_URL", value="https://…", app="shop")`.
- A secret (API keys, tokens, passwords): add `secret=true`. It is stored encrypted, the app
  restarts with it, and nobody – not you, not the platform's API – can read it back; it can only
  be replaced or removed.
- Many at once from a `.env` text: `set_env_file(content="A=1\nB=\"two words\"", app="shop")` –
  one change, one restart. The portal has the same under Variables → Edit as .env.
- Leave `app` out to share a variable with all apps; an app's own value wins.
- `list_env(app=...)` shows names, plain values and where each comes from; `unset_env` removes one.
- Previews (`previews=true`) get the app's variables and secrets when they are built. Set them
  on the app before the pull request is built; otherwise the preview runs without them until the
  next push.

## What to know
- Variables are read at runtime. A static frontend bakes `VITE_…`/`NEXT_PUBLIC_…` values in at
  build time – those belong in the repository and are public anyway.
- `PORT`, `DATA_DIR`, `DATABASE_URL` and `REDIS_URL` are set by the platform.
- Never ask a human to paste a secret into a chat; ask them to add it in the portal (Variables,
  "secret") and tell you the name.
- Names: use the one the provider documents (`ELEVENLABS_API_KEY`, `STRIPE_SECRET_KEY`,
  `OPENAI_API_KEY`), so the code and the human agree without asking.

## A key the app itself defines (an admin key)
The app checks it, nobody issues it, so you generate it. It cannot be read back from the
platform, so keep one local copy that git ignores. Never print it:
```bash
umask 077; python3 -c "import secrets; print(secrets.token_urlsafe(32))" > .myapp-admin-key
grep -qx .myapp-admin-key .gitignore || echo .myapp-admin-key >> .gitignore
```
Set it as a secret from that file, then tell your human where the file is: they need the key to
sign in to the admin pages. To call the app with it, read it from a file instead of typing it,
so it stays out of the shell history and the process list:
```bash
printf 'Authorization: Bearer %s\n' "$(cat .myapp-admin-key)" > /tmp/auth.hdr
curl -H @/tmp/auth.hdr https://myapp.shipholm.dev/api/admin/check
```

## In the app
- Start without the optional ones. A missing key turns its feature off, not the app: answer
  `503 "ADMIN_KEY not set"`, or log mail instead of sending it, until the value arrives.
- Commit a `.env.example` with every name and no values, and keep `.env` in `.gitignore`.
  Generated projects (Lovable and others) often commit a `.env`. Remove it and replace any key
  that was in it.
- A changed secret restarts the app. Read variables at start, not on every request.
