Secrets

Save reusable environment variables in an organization-owned secret. Values are encrypted at rest. Read responses contain names, versions, and usage metadata, they never return the stored values. The API calls secrets variable sets, so routes and fields use environment-variable-sets and variableSetIds.

Create a secret

Set VARIABLE_SET_ID to the returned id:

adapt env create --data '{
  "name": "agent-config",
  "env": {"APP_ENV": "production", "LOG_LEVEL": "info"}
}'

Names are unique within an organization. This create route does not use an idempotency key, after an uncertain response, list the secrets and check for the name before retrying.

Use secrets in a sandbox

Attach secrets with variableSetIds. Add or override values with env:

adapt sandbox create --variable-set "$VARIABLE_SET_ID" --env LOG_LEVEL=debug \
  --label name=configured-worker

You can attach up to 16 secrets. If multiple secrets define the same variable, supply an explicit env override for that name or remove the conflict. The merged sandbox environment is limited to 64 variables and 64 KiB of JSON, with at most 8,192 characters per value.

The sandbox captures the secrets' values and versions at creation. Updating a secret does not change existing sandboxes. Commands inherit that captured environment and can override individual values with their own env.

Inspect and update secrets

List secrets, including their names, variable names, and versions:

adapt env list --limit 50

Inspect a secret and the sandboxes using it:

adapt env get "$VARIABLE_SET_ID"

Set VARIABLE_SET_VERSION to the current version from that response. An update must include that version and the secret's name. Entries omitted from env are kept, a null value removes an entry:

adapt env update "$VARIABLE_SET_ID" --data - <<EOF_JSON
{
  "name": "agent-config",
  "version": $VARIABLE_SET_VERSION,
  "env": {"LOG_LEVEL": "warn", "APP_ENV": null}
}
EOF_JSON

The response returns the next version. A stale version returns 409, fetch the secret again before applying your changes. Changing name renames the secret.

Delete a secret

Delete the sandboxes attached to the secret before deleting it. A secret still in use returns 409:

adapt env delete "$VARIABLE_SET_ID"