Add secrets

A secret is a value your server needs to call its API, like a shared API key or a workspace id. The repository names it; the value lives only in Sokie. It never appears in git, a deploy or a log.

Declare it

Name the secret under secrets in sokie.json, and refer to it wherever the value belongs, as {"secret": "NAME"}:

{
  "upstream": {
    "headers": {
      "X-Workspace": { "secret": "TASKS_WORKSPACE_ID" }
    }
  },
  "secrets": {
    "TASKS_WORKSPACE_ID": {
      "description": "The workspace every call is made in. Tasks shows it under Settings, Workspace."
    }
  }
}

A secret can stand in for an upstream header, for upstream.auth.key when one key serves every caller, or for an OAuth client's clientSecret. Names are upper case with underscores, like STRIPE_API_KEY, and can't start with SOKIE_. The description is for whoever sets it, so say where to find the value.

sokie check keeps the two halves honest: a reference with no declaration is an error, a declaration nothing uses is a warning, and anything in the repository that looks like a real key is an error.

Set it on the server

$ sokie secrets set TASKS_WORKSPACE_ID
TASKS_WORKSPACE_ID for majestic-lobster-123:
Set TASKS_WORKSPACE_ID on majestic-lobster-123. The running server has it now.

The value isn't echoed as you type, and it's never taken as an argument, so it stays out of your shell history. To set one from a script, pipe it in:

echo "$TASKS_WORKSPACE_ID" | sokie secrets set TASKS_WORKSPACE_ID

The command works on the server this directory is linked to; pass --server <slug> for another. You can also set secrets on the server's Secrets tab in the app.

A change reaches the running server straight away. Set a secret before the server's first deploy and that deploy binds it.

Set it for sokie dev

Locally, sokie dev reads secrets from .sokie/dev.env, one NAME=value per line:

TASKS_WORKSPACE_ID=ws_123

.sokie/ must be in .gitignore. sokie init and sokie deploy add it, and sokie dev won't start without it. Edits to the file apply without a restart.

See what's set

$ sokie secrets list
TASKS_WORKSPACE_ID  set 2026-10-18

Values are write-only: neither the CLI nor the app shows one again. To change a value, set it again. To remove one, run sokie secrets unset NAME.

If a secret is missing

A deploy whose definition refers to an unset secret stops before it builds, and says which ones to set:

✗ Set TASKS_WORKSPACE_ID before deploying (`sokie secrets set`).

If a secret is removed from a running server, the tools that need it return an error that names the secret, until it's set again.