Environment Variables (v0.51)

First-class per-key environment variables on vaults replace the legacy config/prod/* secret-path pattern. Each entry is envelope-encrypted, scoped to one or more environments (production, preview, development, or custom), and resolved at deploy time with explicit precedence.

Concepts

Concept	Description
Env var	A named key (DATABASE_URL, STRIPE_KEY, …) with a value targeting specific environments
Environment	Built-in slugs (production, preview, development) plus tier-gated custom environments per vault
Org shared var	Organization-level var linked to multiple vaults — lowest precedence at resolve time
Branch override	Preview var with git_branch set — highest precedence when branch matches
Sensitive var	Write-only for humans after creation (list/get omit value); cannot target Development-only

Resolution precedence

GET /v1/vaults/{id}/env-vars/resolve?environment=preview&git_branch=feat/x returns the final KEY=VALUE map:

1. Org shared vars linked to the vault (lowest)
2. Vault vars for the environment (git_branch IS NULL)
3. Branch overrides where git_branch matches (highest)

Response includes sources mapping each key to "shared", "vault", or "branch_override".

API endpoints

Vault-scoped

Method	Path	Purpose
GET	/v1/vaults/{id}/env-vars	List vars (filter ?environment=)
POST	/v1/vaults/{id}/env-vars	Create var
GET	/v1/vaults/{id}/env-vars/{key}	Get var (?environment=, ?git_branch=)
PATCH	/v1/vaults/{id}/env-vars/{key}	Update var (see Changing environments)
DELETE	/v1/vaults/{id}/env-vars/{key}	Delete var
GET	/v1/vaults/{id}/env-vars/resolve	Resolve final KEY=VALUE set
GET	/v1/vaults/{id}/environments	List environments
POST	/v1/vaults/{id}/environments	Create custom environment
DELETE	/v1/vaults/{id}/environments/{slug}	Delete custom environment

Org-scoped shared vars

Method	Path	Purpose
GET	/v1/org/env-vars	List shared vars
POST	/v1/org/env-vars	Create shared var
PATCH	/v1/org/env-vars/{key}	Update shared var
DELETE	/v1/org/env-vars/{id}	Delete shared var
POST	/v1/org/env-vars/{id}/link	Link shared var to a vault
DELETE	/v1/org/env-vars/{id}/links/{vault_id}	Unlink from vault

Limit: 1,000 vars per vault.

Changing which environments a var applies to

PATCH takes the full environments array — it replaces, it does not merge. Two rules decide whether the request is accepted.

At least one environment. An empty array is refused with "At least one environment must be specified". A variable scoped to nothing cannot be read by anything, so it is not a state worth storing.

A branch only exists alongside preview. git_branch scopes a preview variable to one branch, and it is invalid without preview in the list. So dropping preview has to drop the branch in the same request:

curl -X PATCH "https://api.1claw.co/v1/vaults/$VAULT_ID/env-vars/DATABASE_URL?git_branch=main" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environments":["production"],"git_branch":null}'

git_branch distinguishes three cases: absent leaves it as-is, null clears it, a string sets it. Send null rather than omitting the field when you drop preview; omitting it leaves the old branch attached to a variable that no longer has preview, which the next write rejects.

The CLI does this for you — 1claw env set KEY -e production clears the branch when preview is not in the list.

Selecting the right row

A key can exist more than once in a vault: once per branch scope. The ?environment= and ?git_branch= query parameters pick which row PATCH and DELETE act on. Without them the server matches any row for that key with no branch, which may not be the one you meant.

Example: create and resolve

# Create a production-scoped var
curl -s -X POST "https://api.1claw.co/v1/vaults/$VAULT_ID/env-vars" \
  -H "Authorization: Bearer $ONECLAW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "DATABASE_URL",
    "value": "postgres://prod.example/db",
    "environments": ["production"],
    "sensitive": true
  }'

# Resolve for preview with optional branch
curl -s "https://api.1claw.co/v1/vaults/$VAULT_ID/env-vars/resolve?environment=preview&git_branch=feat/auth" \
  -H "Authorization: Bearer $ONECLAW_TOKEN" | jq

SDK

import { createClient } from "@1claw/sdk";

const client = createClient({ baseUrl: "https://api.1claw.co", apiKey: process.env.ONECLAW_API_KEY! });

await client.envVars.create(vaultId, {
  key: "STRIPE_KEY",
  value: "sk_live_...",
  environments: ["production"],
  sensitive: true,
});

const { vars, sources } = await client.envVars.resolve(vaultId, "production");

See JavaScript SDK — Environment Variables for the full API surface.

CLI

Per-key management (distinct from legacy env pull/push which sync path-based secrets):

1claw env ls production                        # List vars for an environment
1claw env add DATABASE_URL production          # Add var scoped to production
1claw env add API_KEY preview --sensitive      # Sensitive write-only var
1claw env rm DATABASE_URL preview              # Remove from preview
1claw env set DATABASE_URL -e production,preview   # Change which environments a var applies to
1claw env set DATABASE_URL -e preview --branch feat/x   # Scope it to one branch
1claw env set DATABASE_URL -e production --no-branch    # Drop preview and its branch
1claw env environments ls                      # List vault environments
1claw env environments add staging             # Create custom environment
1claw env environments rm staging              # Delete custom environment

Legacy path-based workflows still support environment scoping:

1claw env pull -e production -o .env.production
1claw env push .env -e staging
1claw env run -e production -- npm start

MCP

Tool	Purpose
resolve_env	Returns the resolved KEY=VALUE map for a vault and environment

When the calling agent has env_auto_resolve: true, omit environment and the server uses the agent's tagged environment from the JWT. See Agent Environment Tagging.

Cloud Runtime injection

When a Cloud Runtime starts or rebuilds, the Vault resolves env vars for runtime.environment (plus source_branch as git_branch) and merges them into the container environment. Vault-resolved keys win over env_public. Combined limit: 64 KB. Restart required after env var changes.

Org settings (Settings → Security)

Setting	Key	Effect
Require sensitive prod/preview vars	env.require_sensitive_prod	Forces sensitive: true on production and preview vars
Enforce agent environment scope	env.enforce_agent_environment_scope	Agents may only resolve vars for their tagged environment

Custom environment tiers

Tier	Custom environments per vault
Pro	1
Team	5
Business	12
Enterprise	Unlimited

Dashboard

• Vault detail → Env Variables — CRUD, environment filter, sensitive toggle
• Org Settings → Shared Env Vars — org-level vars and vault links
• Manage Environments dialog on vault detail — built-in + custom slugs

Related

• Agent Environment Tagging (v0.52) — tag agents so resolve auto-fills environment
• CLI integration — full command reference
• MCP integration — resolve_env tool
• Changelog 2026 — v0.51.0