Environment

An environment is a named set of variables. Requests reference them as {{name}}, and switching environments re-points every request at a different deployment.

environments:
  - name: local
    variables:
      baseUrl: http://localhost:8080
      tenantId: acme-dev
  - name: staging
    variables:
      baseUrl: https://api.staging.example.com
      tenantId: acme

Resolution

{{name}} may appear in any string field — URL, header values, query values, body text, gRPC message JSON, GraphQL variables, MCP tool arguments, a file path. The engine resolves them immediately before dispatch.

If a placeholder has no value, the send fails and names it, rather than sending {{name}} as literal text. That is Settings → Sending → Fail on unresolved variables, on by default. The failure message names the variable and, inside a chain, the node.

There is one active environment at a time. Switch it from the header picker or the command palette.

Layering

Values come from more than one place. From weakest to strongest:

1. Collection defaults — a defaults.variables block in the collection file, for values every request in that file should see.
2. The active environment — what the picker selects.
3. Chain outputs — variables a chain produced, including a request’s prerunChain, merged in for that send.

Promoting a value to a variable

Select text in any editable field and the context menu offers URL-encode, URL-decode, and Set as variable…. The last one names the selection from the key immediately in front of it — "token": "…" suggests token, Authorization: Bearer … suggests Authorization, api_key=… suggests api_key — and asks when nothing key-shaped is adjacent.

It is secret-aware. The selection runs through the same scanner that checks a file at save time, and a value that trips it defaults to the keychain rather than writing a literal into an environment you are about to commit.

The dialog also names the seam that follows from that: a request field resolves {{name}} from the environment, so taking the keychain branch leaves a name that an auth provider has to supply. That is the honest split, not an oversight — an environment is a committed file and a keychain entry is not, so nothing can silently bridge them.

Credentials do not go here

Environment variables are committed to git as part of the collection file. Put configuration in them — base URLs, tenant ids, a test user’s id, a feature flag. Do not put tokens, passwords, or API keys in them.

Credentials belong to an auth provider, which fetches them and injects them, or to the OS keychain, which auth definitions reference by name only.

This separation is also what makes the cloud tier safe: sync moves auth definitions between machines and never moves a secret value.

What an agent sees

When agent access is on, tools return environment variable keys and never values. An agent learns that {{baseUrl}} exists and can use the placeholder; it cannot read what it expands to.

An agent can also switch the active environment — set_environment is one of the tools at v0.1.0-preview.10, so “run this against staging instead” does not need you at the keyboard. It requires an in-app approval toast every time, and its result is the new environment’s name and variable keys. Values still never cross.