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

# Manage environments

> Separate dev, staging, and production configurations

Environments let you maintain different versions of prompts, datasets, and parameters across your development lifecycle. This enables you to:

* **Maintain version control**: Pin stable versions to production while testing new versions in development
* **Enable staged deployments**: Promote versions through dev/staging/production pipelines
* **Support A/B testing**: Compare different versions across environments
* **Isolate changes**: Test modifications without affecting production systems

> [!NOTE]
>
> Environments are only available on [Pro and Enterprise plans](https://docs.braintrust.dev/plans-and-limits.md#plans).

## Create an environment

Environments are defined at the organization level. Create one in the UI or with the [`bt` CLI](https://docs.braintrust.dev/reference/cli/environments):

> [tab] UI
>
> 1. Go to \*\* Settings\*\* > [\*\* Environments\*\*](https://www.braintrust.dev/app/~/configuration/environments).
> 2. Click **+ Environment**.
> 3. Enter a name (e.g., "production", "staging", "dev").
> 4. Click **Create environment**.

> [tab] CLI
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt environments create Production --slug production
> ```

## Assign to environments

### Prompts

To assign a prompt to an environment:

> [tab] UI
>
> 1. Go to \*\* Prompts\*\*.
> 2. Open the prompt.
> 3. Click the  icon.
> 4. Select an environment.

> [tab] CLI
>
> List the prompt's versions, then assign one to an environment:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt prompts versions my-prompt
> bt prompts assign my-prompt --version 1234 --environment production
> ```
>
> To remove the prompt from the environment:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> bt prompts unassign my-prompt --environment production
> ```

> [tab] API
>
> Use [`POST /v1/prompt`](https://docs.braintrust.dev/api-reference/prompts/create-prompt) or [`PUT /v1/prompt`](https://docs.braintrust.dev/api-reference/prompts/create-or-replace-prompt) and pass `environment_slugs` to assign the prompt to one or more environments in a single atomic request. If any slug doesn't exist, the entire request fails and no prompt is created.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> curl -X POST https://api.braintrust.dev/v1/prompt \
>   -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "project_id": "your-project-id",
>     "name": "My prompt",
>     "slug": "my-prompt-slug",
>     "environment_slugs": ["dev", "staging"],
>     "prompt_data": {
>       "prompt": {
>         "type": "chat",
>         "messages": [{"role": "system", "content": "You are a helpful assistant"}]
>       },
>       "options": {
>         "model": "gpt-5-mini"
>       }
>     }
>   }'
> ```

Once assigned, load prompts for that environment in your code:

> [tab] SDK
>
> ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> import { loadPrompt } from "braintrust";
>
> // Load from specific environment
> const prompt = await loadPrompt({
>   projectName: "My Project",
>   slug: "my-prompt",
>   environment: "production",
> });
>
> // Use conditional versioning
> const prompt = await loadPrompt({
>   projectName: "My Project",
>   slug: "my-prompt",
>   version: process.env.NODE_ENV === "production" ? "5878bd218351fb8e" : undefined,
> });
> ```
>
> ```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> from braintrust import load_prompt
> import os
>
> # Load from specific environment
> prompt = load_prompt(
>     project="My Project",
>     slug="my-prompt",
>     environment="production"
> )
>
> # Use conditional versioning
> prompt = load_prompt(
>     "My Project",
>     "my-prompt",
>     version="5878bd218351fb8e" if os.environ.get("NODE_ENV") == "production" else None,
> )
> ```

> [tab] API
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> # Load by project ID and slug
> curl "https://api.braintrust.dev/v1/prompt?slug=my-prompt-slug&project_id=PROJECT_ID&environment=production" \
>   -H "Authorization: Bearer $BRAINTRUST_API_KEY"
>
> # Load by prompt ID
> curl "https://api.braintrust.dev/v1/prompt/PROMPT_ID?environment=production" \
>   -H "Authorization: Bearer $BRAINTRUST_API_KEY"
> ```

### Datasets

Environments are attached to [dataset snapshots](https://docs.braintrust.dev/annotate/datasets/manage.md#save-snapshots), not datasets directly. To assign a snapshot to an environment:

> [tab] UI
>
> 1. Go to [\*\* Datasets\*\*](https://www.braintrust.dev/app/~/datasets).
>
> 2. Open the dataset.
>
> 3. Click  **Snapshots** in the toolbar.
>
> 4. Find the snapshot you want to assign, then select **Environments**.
>
> 5. Toggle the environments in the submenu.
>
> > [!TIP]
> >
> > You can also tag and untag environments from [Loop](https://docs.braintrust.dev/loop/capabilities.md#curate-datasets) when working on a dataset page.

> [tab] API
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
> # 1. Create a snapshot
> curl -X POST https://api.braintrust.dev/v1/dataset_snapshot \
>   -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "dataset_id": "DATASET_ID",
>     "name": "prod snapshot",
>     "xact_id": "DATASET_VERSION_OR_XACT_ID"
>   }'
>
> # 2. Upsert the environment association
> curl -X PUT https://api.braintrust.dev/environment-object/dataset/DATASET_ID/ENVIRONMENT \
>   -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "object_version": "SNAPSHOT_XACT_ID"
>   }'
> ```

Once assigned, load the dataset for that environment in your evals:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { Eval, initDataset } from "braintrust";

// Load by environment
Eval("My App", {
  data: initDataset({ project: "My App", dataset: "My Dataset", environment: "production" }),
  task: async (input) => { /* ... */ },
  scores: [],
});

// Load by version name
Eval("My App", {
  data: initDataset({ project: "My App", dataset: "My Dataset", version_name: "version 1" }),
  task: async (input) => { /* ... */ },
  scores: [],
});

// Load by xact_id (less readable, but precise)
Eval("My App", {
  data: initDataset({ project: "My App", dataset: "My Dataset", version: "8234923849293849..." }),
  task: async (input) => { /* ... */ },
  scores: [],
});
```

```python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from braintrust import Eval, init_dataset

# Load by environment
Eval(
    "My App",
    data=init_dataset(project="My App", name="My Dataset", environment="production"),
    task=lambda input: ...,
    scores=[],
)

# Load by version name
Eval(
    "My App",
    data=init_dataset(project="My App", name="My Dataset", version_name="version 1"),
    task=lambda input: ...,
    scores=[],
)

# Load by xact_id (less readable, but precise)
Eval(
    "My App",
    data=init_dataset(project="My App", name="My Dataset", version="8234923849293849..."),
    task=lambda input: ...,
    scores=[],
)
```

### Parameters

To assign a specific parameter version to an environment:

1. Go to [** Parameters**](https://www.braintrust.dev/app/~/parameters).
2. Open the parameter.
3. Click the  icon.
4. Select an environment.

Once assigned, load parameters for that environment in your code:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { loadParameters } from "braintrust";

const params = await loadParameters({
  projectName: "My Project",
  slug: "eval-config",
  environment: "production",
});
```

## Promote versions

Move tested versions from development to production:

1. Test a new prompt or parameter version in the "dev" environment.
2. Run experiments to validate performance.
3. Once satisfied, assign the same version to "staging".
4. After final validation, assign to "production".

This workflow ensures changes are validated before reaching production users.

## Monitor environment changes

Set up [environment alerts](https://docs.braintrust.dev/observe/alerts.md#create-an-environment-alert) to get notified via webhook or Slack when prompt, dataset, or parameter versions are assigned to or removed from environments. Use these to track deployments, maintain audit trails, or trigger downstream CI/CD workflows.

## Common patterns

### Three-tier deployment

Maintain dev, staging, and production environments:

* **dev**: Latest changes, frequent updates, used by developers.
* **staging**: Pre-release testing, stable versions.
* **production**: Customer-facing, only validated versions.

### Feature flags

Use environments to control feature rollouts:

* Create an environment for each feature flag.
* Assign different prompt, dataset, or parameter versions based on flag state.
* Gradually roll out by changing environment assignments.

### A/B testing

Test variations by environment:

* Create environments for each variant (e.g., "variant-a", "variant-b").
* Assign different prompt, dataset, or parameter versions to each.
* Route users to different environments based on A/B test assignment.
* Compare performance using environment filters.

## Next steps

* [Create prompts](https://docs.braintrust.dev/evaluate/prompts/create.md)
* [Version prompts](https://docs.braintrust.dev/evaluate/prompts/versions.md) across environments


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