Skip to main content
Environment variables let you inject API keys, database URLs, and other configuration into every task container. Whim supports multiple scopes so teams can share common config while individual members can add their own secrets.

​
Scopes and precedence

Environment variables are resolved from three levels. Higher-priority levels override lower ones when the same key appears at multiple levels.
PriorityScopeSet byApplies to
HighestWorkspace user overridesIndividual memberTasks in this workspace only
MiddleUser defaultsIndividual memberAll workspaces the member belongs to
LowestWorkspace defaultsWorkspace adminAll members in this workspace
When the same variable key exists at multiple levels, the highest-priority level wins. For example, if a workspace default sets DATABASE_URL and a member overrides it in their workspace user config, the member’s value is used for their tasks.

​
Adding environment variables

​
Workspace-level variables

Workspace admins can set variables that apply to all members:
  1. Open Workspace Settings > Configuration > Workspace Defaults tab
  2. Scroll to the Environment Variables section
  3. Add key-value pairs in the .env editor
  4. Click Save

​
User-level variables

Members can set personal variables that apply across all their workspaces:
  1. Open Settings > Configuration > User Defaults tab
  2. Scroll to the Environment Variables section
  3. Add your key-value pairs
  4. Click Save

​
Per-workspace user overrides

For workspace-specific personal overrides:
  1. Open Settings > Configuration > My Workspace Overrides tab
  2. Scroll to the Environment Variables section
  3. Add or override variables for this workspace only
  4. Click Save

​
Multi-file support

Environment variables are organized into .env files. You can create multiple files following the .env / .env.<suffix> naming convention (e.g., .env.local, .env.production, .env.test). Files are processed in order: .env first, then additional files alphabetically. If the same key appears in multiple files, the later file takes precedence.

​
Secret masking

Whim automatically detects likely secrets based on key names and masks their values in the UI. Variables with keys matching common patterns are treated as secrets:
  • Keys containing secret, password, or token
  • Keys matching patterns like API_KEY, ACCESS_KEY, PRIVATE_KEY
Secret values display as dots instead of plain text. You can toggle the secret status of any variable using the lock icon in the editor.
Secrets are masked in the UI for display purposes. They are stored encrypted at rest in the database and injected securely into containers.

​
Disabling workspace variables

Members can disable specific workspace-level variables without removing them from the workspace. This is useful when a workspace variable conflicts with your personal setup. Disabled variables are filtered out before merging, so they won’t appear in your task containers even though they remain configured at the workspace level.

​
How variables are injected into containers

When a task starts, Whim resolves environment variables from all three levels and injects them into the container in two ways:
  1. As environment variables — merged directly into the container’s environment for immediate access via process.env or equivalent.
  2. As .env files — written to the /app directory inside the container (e.g., /app/.env, /app/.env.local), where application frameworks can discover them automatically.

​
System variables

Whim also injects system variables that provide task context. These cannot be overridden by user-defined variables:
VariableDescription
WHIM_AI_PROVIDERThe configured AI provider (e.g., claude, codex)
WHIM_AI_RUNTIMEThe AI runtime in use
WHIM_TASK_IDThe current task’s unique identifier
WHIM_WORKSPACE_IDThe workspace identifier
WHIM_TEAM_IDThe team identifier
WHIM_GITHUB_TOKENGitHub access token for Git operations
WHIM_CLONE_URLThe repository clone URL

​
Common use cases

API keys

Store third-party API keys (OpenAI, Stripe, etc.) as workspace variables so every task can access external services.

Database URLs

Set DATABASE_URL at the workspace level so all tasks connect to the right database without manual configuration.

Build secrets

Store tokens like NPM_TOKEN for use with workspace image builds via the buildSecrets configuration.

Feature flags

Use per-user overrides to enable or disable features for individual members during development.