Skip to main content
Environments let you maintain different versions of prompts, functions, and configurations across your development lifecycle. Test changes in development before promoting them to production.

​
Create an environment

Environments are defined at the project level:
  1. Navigate to Configuration > Environments.
  2. Click + Environment.
  3. Enter a name (e.g., “production”, “staging”, “dev”).
  4. Optionally set as the default environment.
  5. Click Create.
Every project starts with no environments. When no environment is specified, the latest version of each prompt or function is used.

​
Assign versions

Assign specific prompt or function versions to environments:
  1. Open a prompt in the editor.
  2. Click Environments in the sidebar.
  3. Select an environment from the dropdown.
  4. Choose which version to assign.
  5. Click Save.
The assigned version will be used when calling the prompt with that environment parameter.

​
Use environments in code

Specify the environment when calling prompts or functions: 
import { invoke } from "braintrust";

const result = await invoke({
  projectName: "My Project",
  slug: "summarizer",
  environment: "production",
  input: { text: "Long text to summarize..." },
});
Without an environment parameter, the latest version is used.

​
Load prompts with environments

Use loadPrompt to load prompt configurations with environment parameters: 
import { loadPrompt } from "braintrust";

// Load from specific environment
const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "my-prompt-slug",
  environment: "production",
});

// Use conditional versioning
const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "my-prompt-slug",
  version: process.env.NODE_ENV === "production" ? "5878bd218351fb8e" : undefined,
});

​
Use the REST API

Load prompts with environment parameters via HTTP: 
# 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"

​
Use environments for logging

Set the environment when initializing loggers to separate dev and production logs: 
import { initLogger } from "braintrust";

const logger = initLogger({
  projectName: "My Project",
  environment: process.env.NODE_ENV || "dev",
});
Logs are tagged with the environment, making it easy to filter production logs from development logs.

​
Promote versions

Move tested versions from development to production:
  1. Test a new prompt 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.

​
Set default environments

Mark an environment as default to use it when no environment is specified:
  1. Navigate to Configuration > Environments.
  2. Click the ··· menu next to an environment.
  3. Select Set as default.
The default environment is used when calling prompts without an explicit environment parameter.

​
Filter by environment

In the Logs page, filter by environment to view requests from specific contexts:
  • Use the filter bar: environment = "production".
  • Use the Environment filter dropdown.
  • Group by environment to compare metrics across environments.

​
Monitor environment changes

Set up environment alerts to get notified via webhook or Slack when prompt 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 versions based on flag state.
  • Gradually roll out by changing environment assignments.

​
A/B testing

Test prompt variations by environment:
  • Create environments for each variant (e.g., “variant-a”, “variant-b”).
  • Assign different prompt versions to each.
  • Route users to different environments based on A/B test assignment.
  • Compare performance using environment filters.

​
Next steps