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
.envtext: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
appout 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_envremoves 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_URLandREDIS_URLare 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:
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:
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.examplewith every name and no values, and keep.envin.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.
Use when: 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.
For agents: get_skill("shipholm-env-and-secrets") over MCP, or the SKILL.md at https://api.shipholm.com/skills/shipholm-env-and-secrets/SKILL.md.