Secrets and environment

Where a devbox's environment variables come from, which layer wins, and where real secrets belong.

A devbox builds its environment from several places at once. Knowing which one wins saves you a confusing hour, so here is the whole story on one page.

Repo secrets — where real secrets go

Secrets belong in the Repo secrets tab on the devbox page. They are stored per repository, not per machine, which means:

Every devbox of that repo gets them, including ones you create later.
They survive a devbox expiring. The next devbox for the repo is born configured.
They are write-only. Sokko stores the value and never shows it again — your agents can see which names are set, never the values.
Only owners and admins can change them.

Add a value, then redeploy. The new environment lands on the next deploy, not on the running stack.

Never put a secret anywhere else. Not in sokko.devbox.yml, not in a message to your agent, not in a per-deploy override. Everything you say to an agent travels through a model and sits in the conversation. Repo secrets are the one path that does not.

Missing variables fail fast

If your compose file or your code references a variable that has no source anywhere, the deploy is refused before anything is built, with ENV_MISSING naming the exact variables.

That is on purpose. The alternative is a stack that comes up, half works, and fails somewhere deep in a request an hour later. The dashboard turns that error into a shortcut straight to the Repo secrets tab with the name pre-filled: add the value once, redeploy, done.

The order things are applied

Later layers overwrite earlier ones.

	Layer	Where it comes from	Good for
1	Repo defaults	A committed `.env`, and `environment:` / `env_file:` in your compose file	Dev database URLs, feature flags, anything already in your repo
2	`env:` in `sokko.devbox.yml`	The file you committed	Non-secret config that is specific to previews
3	Per-deploy overrides	Values your agent passes on one deploy	A toggle you want for a single test run
4	Repo secrets	The dashboard tab above	Every real credential
5	Sokko's own variables	Set automatically	See below

Layer 4 beating layer 3 is deliberate: an override that came out of a chat must never be able to shadow a credential a human entered.

If your agent supplied a run command with an env map, that sits at layer 2 — the same rung as the committed file, because it is the same kind of value.

What Sokko sets for you

Every devbox stack gets these, applied last:

Variable	Value
`PORT`	The port your app should listen on
`HOST`	`0.0.0.0`
`PUBLIC_URL`	The devbox's preview URL
`SOKKO_DEVBOX`	`1` — use it to branch behaviour in preview

Frameworks that read PORT need no flags from you at all. SOKKO_DEVBOX is the clean way to disable analytics, use a test payment key, or skip a cron in a preview.

A handful of names are reserved by the platform and are rejected if you try to set them. The error names the surface that owns each one.

Rotating a value

Change it in the Repo secrets tab, then redeploy. The running stack keeps the old value until it is replaced — nothing is swapped underneath a running process.

Removing a name works the same way: it disappears from the next deploy, and a deploy that still needs it fails with ENV_MISSING rather than starting without it.

What is not shared

Repo secrets are scoped to one repository inside one organization. A devbox for a different repo sees none of them, and no other organization ever does — not even one previewing the same public repo.