> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

> Give an agent a different value per environment (dev, staging, prod), see which value a call reads, why it outranks call-start values, and where secrets fit.

Environment variables hold settings that change between environments but not between calls: an API host, a test account, a support line. Each key has one value in dev, one in staging and one in prod, and the agent reads the value of the environment the call runs in. You write the key in prompts and tools as `{{API_HOST}}`, so the same version can call a test endpoint in staging and the real one in prod.

They work in flow agents and single prompt agents. See [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md) for how versions move between environments.

## Add an environment variable

**1. Open the environments grid**

Open the **Variables** dialog (in a flow agent, **Variables** on the canvas toolbar; in a single prompt agent, **Variables** > **Manage variables**) and click **Manage** next to **Environment variables**.

**2. Add a key**

Click **Add key** and type the key in capital letters, for example `API_HOST`.

**3. Fill in every environment**

Type a value in the column for each environment. Use **Copy to other environments** to copy one value into the environments that have none.

**4. Save**

Click **Save**. If a cell is empty, saving is blocked: "Every key needs a value in every environment. Fill the cells marked in red."

![The environments grid with the keys API\_HOST, SUPPORT\_NUMBER and STORE\_REGION down the side and dev, staging and prod across, the staging SUPPORT\_NUMBER cell being edited](https://mintcdn.com/hamsa-452fa79a/7GY0-8K2sfzXu6G7/images/agents/variables/environments-grid-light.webp?fit=max\&auto=format\&n=7GY0-8K2sfzXu6G7\&q=85\&s=49f5977900af6c1109f848daeb43e2e8)

You can also edit values in **Releases**, on the **Env variables** tab: click a value to change it, or use **Add environment variable**.

To add many keys at once, use **Import .env** and paste one `KEY=value` per line into the environment you choose. To download one environment's values, open that environment's column menu and choose **Export .env**.

### Key and value rules

| Rule | Message |
| - | - |
| Capital letters, numbers and underscores, starting with a letter | "Use capital letters, numbers and underscores, starting with a letter, like API\_HOST." |
| Up to 64 characters | |
| Each key once | "This key is already listed above." |
| Not the name of another variable on the agent (dynamic, extracted or local) | "Another variable already uses this name. Pick a different key." |
| Not the name of a [system variable](https://docs.tryhamsa.com/agents/variables/system-variables.md) | "A key matches the name of another variable. Names are shared, so one would shadow the other." |
| A value in every environment, up to 4,096 characters | "Every key needs a value in every environment. Fill the cells marked in red." |

## Use an environment variable

Write the key in braces wherever variables work: `{{API_HOST}}` in an API tool's URL, `{{SUPPORT_NUMBER}}` in a transfer step. The lowercase form, `{{api_host}}`, reads the same value.

Environment variables are available in every step, wherever the step is in the flow.

When a flow uses a key that no environment defines, the grid says "This flow references API\_HOST, which no environment defines." Click **Add them** to add the missing keys.

## Which environment a call reads

| The call | Reads values from |
| - | - |
| A call to a number, the website widget or the SDK | The environment it lands in. Without deployments, that's prod. |
| A call to a version | The environment that version is published to |
| A test call on your draft | dev (prod when deployments are off), with your [test values](https://docs.tryhamsa.com/agents/variables/test-values.md) on top |

The agent reads the values when the call starts. A change reaches the next call: "Calls in prod read it from the next call." For prod: "Reaches live calls right away. No new version needed."

## Environment values outrank call-start values

When a value sent at call start in `params` has the same name as an environment variable, the environment value wins. A caller can't change your agent's configuration by sending their own `api_host`.

This matters most for web calls, because anyone can see and change what a web page sends. Keep every setting the caller must not change in environment variables, and use [dynamic variables](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md) for data that differs per call.

## Environment variables and secrets

Put credentials (API keys, tokens, passwords) in [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md), not in environment values. Reference a secret in a tool's settings as `{{secrets.NAME}}`.

An environment value can't hold a secret: a value that references one is never sent to calls, so the key reads empty everywhere, tools included. Reference the secret in the tool instead.

Write `{{secrets.NAME}}` only in tool settings, where the editor offers it. A secret written in a prompt or message would be filled in there too and sent to the model, where it could end up in the conversation.

## Who can change values

Anyone in the project can see the values. To change them you need permission to edit the agent, plus the permission for that environment:

| Environment | Permission |
| - | - |
| dev | Publish |
| staging | Promote |
| prod | Update live values |

Owners and admins have all three. Without them you see: "Only people who put versions in an environment change its values. To try your own, use Test values in the Test menu." See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Good to know

* Every agent has dev, staging and prod; they can't be renamed or removed.
* An agent with deployments off has one environment as far as calls are concerned: prod.
* On a [Transfer to agent](https://docs.tryhamsa.com/agents/flow/steps/transfer-agent.md), the receiving agent uses its own environment values, never the first agent's.
* To try a new key or value without changing an environment, use [test values](https://docs.tryhamsa.com/agents/variables/test-values.md). A new key added there joins dev when your changes are merged.

## Related

> [card] [Environments and releases](https://docs.tryhamsa.com/agents/release/environments.md)
>
> Promote versions between dev, staging and prod.

> [card] [Test values](https://docs.tryhamsa.com/agents/variables/test-values.md)
>
> Try your own values in draft test calls.

> [card] [Secrets](https://docs.tryhamsa.com/agents/tools/secrets.md)
>
> Store credentials for tools.

> [card] [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md)
>
> Per-call data from the API, SDK and batch calls.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.