Key idea
Variables are like your .env file, but stored per environment on ComputeSphere. Use a variable for settings anyone on the project may read, and a secret for anything that grants access; secrets can never be read back.
The same image runs in staging and in production. What changes between them is configuration: which database, how much logging, which payment keys. Keeping it in variables, outside the image, means you change it without rebuilding.
Two kinds of value
- Variables are for settings that aren't sensitive:
LOG_LEVEL,REGION, a public URL. The console shows them in full, and anyone with access to the project can read them. - Secrets are for passwords, API keys, tokens and
DATABASE_URL. They're write-only: once saved, nobody can read the value back, in the console, the CLI or the API. The console shows the key name and dots.
Your app can't tell them apart. Both arrive as ordinary environment variables, read the usual way (process.env.API_KEY, os.environ["API_KEY"], os.Getenv("API_KEY")).
Keep each secret's real value somewhere you control, such as a password manager. If you lose it, you set a new one; ComputeSphere can't give the old one back.
Two levels: environment and service
Set per environment, inherited by services
Shared variables & secrets
Shared variables & secrets
Only NEXT_PUBLIC_… and VITE_… variables. Frameworks copy them into files sent to browsers.
Secrets never. Don't put a secret in one of these.
Every variable and secret, as an ordinary environment variable.
Your app can't tell them apart.
Values set on the environment are shared: every service in it inherits them. A service can set the same key for itself, an Override, and its value wins. Remove the override and the environment's value applies again. Because each environment has its own set, production values never appear in staging.
Setting them in the console
- For a service: open the service, go to Settings, and find the Environment variables card. It has two tabs, General for variables and Secrets. Choose Edit, add or change rows, then Save. Save one tab at a time.
- For an environment: open the environment, go to its Settings tab, and use the Shared Variables & Secrets card.
Use the console for secrets while you're learning. It keeps your other secrets when you save one.
When you save a service's variables, the console asks whether to redeploy. That's the next lesson.
Setting them with csph
csph services variables set KEY=value: add or change a service's variables.csph services variables listandunset KEY: show values, or remove one so the environment's value applies again.csph services secrets set KEY=valueandsecrets list: set secrets; the list shows names only.csph environments variables setandenvironments secrets set: the same for shared values.
Service commands take --service <service-id>, plus --environment <environment-id> unless you've set a default with csph environments use. Lesson 5.1.1 shows how to find any ID.
Careful with secrets set. Secrets are stored as a whole set and csph can't read the old values, so it refuses unless you list every existing secret again. --replace keeps only the ones you give and deletes the rest. Take values from your shell, never typed into the command (lesson 5.8.1):
csph services secrets set API_KEY="$API_KEY" DATABASE_URL="$DATABASE_URL" \
--service <service-id> --environment <environment-id>
Names use letters, digits and underscores, can't start with a digit, and can be up to 63 characters.
Check yourself