Skip to main content
A secret is a named value, such as HF_TOKEN or WANDB_API_KEY, that every instance and job launched in an environment gets as an environment variable. Set your tokens once, and every machine has them, without the values ever going into a command, a launch script or your agent’s context.

​
What they are

  • Named per environment. A secret applies to one or more environments of the workspace. Machines launched in production get the secrets that apply to production, and nothing that applies only to staging. One name has at most one value in an environment.
  • Set in the dashboard. A workspace Owner or Manager adds, changes and removes secrets in Settings > Secrets (open it). You can type them one by one, or paste or drop a .env file. Everyone in the workspace can see which names exist.
  • Read, by name only, everywhere else. The API, the MCP server, the CLI and the SDKs list the names of an environment’s secrets, never their values, and none of them can set one.

​
How launches get them

When a machine starts, it fetches its variables from Runcrate and every shell on it has them: SSH sessions, the web terminal, the code editor, and a job’s command (also inside the job’s container image). A command reads them like any other variable:
A machine gets its variables in this order, a later one winning over an earlier one of the same name:
  1. The environment’s secrets.
  2. Values set for this launch: the variables in the launch sheet, env_vars on POST /api/v1/instances, env on a job (runcrate run --env KEY=value, variables in the MCP run_job tool), or env / env_vars in a schedule’s spec.
  3. Runcrate’s own variables, such as RUNCRATE_ENVIRONMENT, RUNCRATE_INSTANCE_ID and, for jobs, RUNCRATE_JOB_ID. Names starting with RUNCRATE_ are reserved, so a secret can never replace them.
So a one-off value passed with a launch (--env HF_TOKEN=hf_other) overrides the environment’s HF_TOKEN for that launch only. Changes apply to the next launch. A machine that is already running keeps the values it started with, so relaunch it to pick up a changed secret. A job whose machine cannot fetch its variables does not run its command and fails, rather than running without them. Reruns and retries get the environment’s secrets as they are at that launch.

​
Limits

​
Sensitive secrets

Mark a secret Sensitive when nobody should ever read it back, such as a production database password. Its value is then hidden in Runcrate for everyone, including Owners, from then on. Every machine launched in its environments still gets it. A secret that is not sensitive can be revealed in the dashboard by an Owner or Manager, and every reveal is written to the audit log. Sensitive cannot be turned off again: to change that, delete the secret and add it again.

​
From the MCP server, CLI and SDKs

All of them show the secrets of the environment they act in: the one your agent connected to, the one runcrate envs switch picked, or the one your API key belongs to.
Ask your agent “which secrets does this environment have?”. The list_secrets tool returns each name, whether it is sensitive, and when it last changed. When a job needs a token that is not there, the agent asks you to add it in the dashboard instead of asking you to paste it into the chat.

​
How they are kept safe

  • Encrypted at rest. Each value is encrypted (AES-256-GCM) with a key kept outside the database, and each ciphertext only decrypts as the secret it was written for. The values you set for one launch are stored the same way.
  • Never shown back. No API, MCP tool, CLI command or SDK returns a value. Lists, schedules and jobs show names only (env_keys). In the dashboard only a non-sensitive secret can be revealed, by an Owner or Manager, and the reveal is recorded.
  • Not in launch scripts. Values never travel in a machine’s startup script or its stored settings. Each machine fetches its own variables once, at boot, with a credential that only works for that machine and only for a short time after it starts.
  • Out of agents’ hands. An agent connected over MCP, or the CLI signed in with runcrate login, can list names but can never add, change or reveal a secret, even when the person who connected it is an Owner.
  • Audited. Adding, changing, removing and revealing a secret is recorded in the audit log with who and when, never with the value.
A job’s command, its logs, and a schedule’s launch_script and startup_commands are visible to everyone in the workspace. Keep tokens and passwords in secrets, or in launch values, never in the command itself. Anything your own program prints to the job log is visible too.