Environments and secrets

• A variable is a plain value. Commands in the sandbox see it, and members see it in the console and API.
• A secret is write-only. No API route returns its value, and the sandbox never sees it. Commands see a placeholder, and the host swaps in the real value on HTTPS requests to the hosts you allow.

Set up an environment

import { Zode, Sandbox } from "@zodedev/sdk";

const zode = new Zode();
await zode.environments.create("staging");
await zode.environments.setVariable("staging", "APP_ENV", "staging");
await zode.environments.setSecret("staging", "STRIPE_KEY", {
  value: process.env.STRIPE_KEY!,
  allowedHosts: ["api.stripe.com"],
});

const sbx = await Sandbox.create({ environment: "staging" });

API=https://api.zode.dev
AUTH="Authorization: Bearer $ZODE_API_KEY"
JSON="Content-Type: application/json"

ENV=$(curl -sS -X POST $API/v1/environments -H "$AUTH" -H "$JSON" \
  -d '{"name":"staging"}' | jq -r .id)

curl -sS -X PUT $API/v1/environments/$ENV/variables/APP_ENV -H "$AUTH" -H "$JSON" \
  -d '{"value":"staging"}'

curl -sS -X PUT $API/v1/environments/$ENV/secrets/STRIPE_KEY -H "$AUTH" -H "$JSON" \
  -d "{\"value\":\"$STRIPE_KEY\",\"allowed_hosts\":[\"api.stripe.com\"]}"

curl -sS -X POST "$API/v1/sandboxes?environment=staging" -H "$AUTH" -H "$JSON" \
  -d '{"vcpus":2}'

Which environment a sandbox reads

• zode new has no environment flag, so sandboxes made with the CLI read default.
• A fork reads its parent’s environment.
• You cannot move a sandbox to another environment after it is made.
• Deleting an environment unlinks its sandboxes; their next commands get nothing from it.

When values are read

Per-command variables

zode exec -e DEBUG=1 -e AWS_REGION demo -- npm test   # AWS_REGION alone passes your local value
zode ssh --env-file .env demo

await sbx.exec("npm test", { env: { DEBUG: "1" } });

curl -sS -X POST https://api.zode.dev/v1/sandboxes/$ID/exec \
  -H "Authorization: Bearer $ZODE_API_KEY" -H "Content-Type: application/json" \
  -d '{"command":"npm test","env":["DEBUG=1"]}'

How secrets work

1. You store a secret with a value and allowed_hosts, for example api.stripe.com or *.example.com (any subdomain, not the apex).
2. Commands in the sandbox see STRIPE_KEY=zode_vault_..., a placeholder that is the same in every session.
3. Your code uses it as usual, for example Authorization: Bearer $STRIPE_KEY.
4. TCP traffic from the sandbox to ports 443 and 80 leaves through an egress proxy on the host. For hosts on a secret’s allowlist, the proxy decrypts the request, finds the placeholder in the URL, headers or body, and swaps in the real value.

What this protects against

What it does not protect against

• Use of the secret. Code in the sandbox can still call the allowed hosts with your key, and do anything the key permits. Give sandboxes keys with the narrowest scope your provider offers.
• Hosts that echo requests. If an allowed host returns request headers or bodies in its responses, the real value comes back into the sandbox. Allow only the API hosts that need the key.
• Variables. Variables are plain values inside the sandbox. Put anything sensitive in a secret.

Limits

• Only bearer tokens and header keys for HTTPS APIs. Request-signed credentials and connection strings are refused with 400 secret_unsupported: names starting with AWS_SECRET_ACCESS_KEY or AWS_SESSION_TOKEN, and values starting with postgres://, postgresql://, mysql://, mongodb://, mongodb+srv://, redis:// or -----BEGIN. Use short-lived credentials for those.
• Swapping works on port 443 only. Other ports are not proxied, so a placeholder sent to them goes out unchanged.
• Clients that pin certificates fail against allowed hosts, because the proxy presents its own certificate.
• Requests to allowed hosts use HTTP/1.1, and request bodies over 32 MiB are refused with 413.
• No secrets reach custom image builds.

Limits