Skip to main content

Documentation Index

Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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
only available on Pro and Enterprise plans.

​
Create an environment

Environments are defined at the organization level:
  1. Go to Settings.
  2. Click Environments.
  3. Click + Environment.
  4. Enter a name (e.g., “production”, “staging”, “dev”).
  5. Click Create environment.

​
Assign to environments

​
Prompts

To assign a prompt to an environment:
  1. Go to Prompts.
  2. Open the prompt.
  3. Click the icon.
  4. Select an environment.
Once assigned, load prompts for that environment in your code: 
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,
});

​
Datasets

Use POST /v1/dataset or PUT /v1/dataset and pass environment_slugs to assign the dataset to one or more environments in a single atomic request. If any slug doesn’t exist, the entire request fails and no dataset is created. 
curl -X POST https://api.braintrust.dev/v1/dataset \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "your-project-id",
    "name": "My dataset",
    "environment_slugs": ["dev", "staging"]
  }'
Once assigned, load the dataset for that environment in your evals: 
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: [],
});

​
Parameters

To assign a specific parameter version to an environment:
  1. Go to Parameters.
  2. Open the parameter.
  3. Click the icon.
  4. Select an environment.
Once assigned, load parameters for that environment in your code: 
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 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