---
title: Pass secrets
description: Pass environment variables, and broker secrets to the hosts that need them.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reeval.ai/llms.txt
> Use this file to discover all available pages before exploring further.

The `env` field sets variables in the sandbox. reeval copies a string in as its value. Pass an API key with `secret` and the `hosts` it goes to, so the key stays on the host.

## Keep API keys on the host

reeval puts a placeholder in the sandbox, `reeval_secret_` followed by 32 characters. The egress gateway swaps in the real key on an HTTPS request to a host you name, and puts the placeholder back in that host's response.

Put the key in the `.env.local` file next to the `reeval.config.ts` file:

```bash title=".env.local"
GOOGLE_GENERATIVE_AI_API_KEY=replace-with-your-key
```

A variable exported in the shell takes precedence over the `.env.local` file, and that file takes precedence over the `.env` file.

A secret without `hosts` is the real value in the sandbox, and `reeval run` warns about it. To refuse it, see [Broker a secret to a host](#broker-a-secret-to-a-host).

For more information about which hosts the sandbox can reach, see [Egress](/configuration/environments/egress).

## Pass a secret

In the `evals/gemini.eval.ts` file, take `secret` from the helpers and read the host variable with `secret.fromEnv()`:

```ts title="evals/gemini.eval.ts"
import { defineEnvironment, evaluate, expect } from '{{ pkg }}'

const gemini = defineEnvironment('gemini', ({ secret }) => ({
  env: {
    GEMINI_API_KEY: secret.fromEnv('GOOGLE_GENERATIVE_AI_API_KEY', {
      hosts: secret.hosts.gemini,
    }),
  },
}))
```

The sandbox's `GEMINI_API_KEY` holds the placeholder. reeval records the name and redacts a value of four or more characters in everything it writes. For more information about the `secret()` shorthand and the options that change who receives a secret, see [`secret.fromEnv`](/reference/environment-helpers#secretfromenv). For more information about secrets in MCP server headers, see [Add a remote server](/configuration/environments/mcp-servers#add-a-remote-server).

## Broker a secret to a host

Broker the key, refuse unbrokered secrets, and check the plan in this order.

1. Name the hosts the key is sent to in `hosts`, as `secret.hosts.gemini` does above.

   Use a provider preset, or a list of hosts you choose. For every preset, wildcards, and where the key is substituted, see [`secret.hosts`](/reference/environment-helpers#secrethosts).

2. In the `reeval.config.ts` file, refuse a secret without `hosts`, which the sandbox would hold as the real key:

   ```ts title="reeval.config.ts"
     secrets: { unbrokered: 'error' },
   ```

3. Print the plan:

   ```bash
   npx reeval run --dry-run
   ```

   The notes name each brokered variable and its hosts:

   ```text
   brokered: GEMINI_API_KEY → generativelanguage.googleapis.com
   ```

For runnable projects, see [`with-brokered-secret`](https://github.com/invertase/reeval/tree/main/examples/with-brokered-secret), [`with-strict-secrets`](https://github.com/invertase/reeval/tree/main/examples/with-strict-secrets), and [`with-secret-for-checks`](https://github.com/invertase/reeval/tree/main/examples/with-secret-for-checks), which gives a secret to the assertions only.

## Reference

For more information about `secret`, `secret.fromEnv`, `secret.template`, and `secret.hosts`, see [`secret.fromEnv`](/reference/environment-helpers#secretfromenv). For more information about `secrets.unbrokered`, see [`secrets`](/reference/options#secrets). To set a variable that isn't a secret, see [the `env` option](/reference/options#env).