Environments, variables and secret files

To set environment variables and secrets for a sandbox, you put them in an environment on your workspace and pick that environment when you launch. An environment is just a name, development, staging, production. What it holds is a flat list of values, each one a variable or a file, and each one plain or secret. A session launches with exactly one environment, and its values are delivered into the sandbox at creation.

The two kinds of value

A file path may not start with / or contain .., so a file can only ever land inside the workspace tree. A value of either kind is at most 32 KB, an environment holds up to 200 values, and a workspace up to 20 environments.

Each value is plain or secret. A plain value is stored in clear and shown in the editor. A secret is encrypted at rest and write-only: it is never returned, not to the website, not to a chat, not to an MCP client. Saving the editor without retyping a secret keeps the stored one. Flipping a value from plain to secret encrypts what is there; flipping it back never decrypts it into something readable.

A secret can also be declared with no value yet. That is how you say "this must be filled in": the name is in the list, hasValue is false, and the launch omits it rather than exporting an empty string that could mask a real variable in the container.

Writing values

The website shows one environment at a time and saves it as a whole. The action behind that form is environment_values_set, which any door can call:

{
  "workspaceId": "shop-api",
  "environment": "staging",
  "values": [
    { "kind": "var", "key": "DATABASE_URL", "secret": true, "value": "postgres://..." },
    { "kind": "var", "key": "LOG_LEVEL", "value": "debug" },
    { "kind": "file", "key": ".env.local", "secret": true, "value": "STRIPE_KEY=sk_test_..." }
  ]
}

The call replaces that environment's set: a key you leave out is deleted. /values shop-api in staging lists what an environment carries, which entries are secret and which secrets still have no value. It never prints a value.

Picking an environment at launch

The first name in the workspace's list is the default. Name another one when you launch:

/launch shop-api in staging

A name the workspace does not have is refused rather than silently swapped for the default, so a session never comes up with the wrong values. The session remembers which environment it launched with; session_changes compares a fingerprint of each delivered value against the environment's current one and names what changed, without ever showing a value.

How values reach the sandbox

The values are decrypted on Isolation Cloud only long enough to be sealed to the server that will run the session, using a key derived from that server's pairing secret. The server unseals them and materializes them for the sandbox: variables into the process environment, files at their paths, with mode 0600, for the lifetime of that sandbox. Nothing is written to a log, passed in a command line, put in a URL, saved into the workspace bundle or committed to git. When the session finishes, the materialized copies are gone. The full path is in how secrets travel.

Cloning and renaming

environment_clone makes a new environment with a copy of another's values, secrets included and still encrypted. It is the usual way to make staging from production without retyping anything, then change the two values that differ.

environment_rename renames an environment and moves its values with it. Use it instead of editing the workspace's environment list: the list alone cannot tell a rename from a delete plus a create, and a delete takes every value with it. Sessions launched under the old name follow the rename, so their next restart still finds their environment.

Renaming one value in place, DATABASE_URL to DB_URL, keeps its ciphertext. Deleting and re-adding it would lose the stored secret.

Restart to apply

Values are baked in when the container is created, so editing an environment changes nothing in a session that is already running. Run /restart on the session. It seals the environment's current values, recreates the container and reattaches the session's files and windows; processes inside stop, which is why an agent cannot ask for it. /restart in production restarts the same session with a different environment of the same workspace. Suspending and resuming a session, by contrast, keeps its container as it was; see suspend, resume, finish.