Environments

Introduction to Environments

Vellum provides first-class support for managing different deployment stages through Environments. Environments allow you to maintain proper isolation between your development, staging, and production workflows while providing a unified management experience.

Environment-Scoped Resources

All major Vellum resources are scoped to specific Environments, ensuring complete isolation between your different deployment stages. The Vellum UI shows your active environment at the top of most pages, making it clear which environment context you’re working in.

API Keys

Each API key is scoped to a specific Environment. When you make an API call, it performs actions within the context of the Environment from which the API key was created. This ensures that your development API calls never accidentally affect your production data.

API Keys are created under Workspace Settings at https://app.vellum.ai/organization?tab=0&workspace-settings-tab=environments

Releases

Each Deployment maintains separate Release history per Environment. You can deploy different versions to your various environments independently, allowing you to test changes in development and staging before promoting them to production.

Document Indexes

Documents uploaded to a Document Index are Environment-scoped and only appear in search results within the same Environment context. This ensures that your development documents don’t interfere with production search results.

Monitoring Data

Execution and monitoring data are filtered to show only requests made within the active Environment context. Use the Environment picker at the top of the page to switch between different Environment data views.

Recommended Approach

For optimal organization and workflow management, we recommend:

One Deployment per Prompt/Workflow Sandbox

Instead of creating separate deployments for each environment, use a single deployment and leverage Environments for isolation. This approach:

• Reduces complexity in managing multiple deployments
• Provides better organization and visibility
• Takes full advantage of Environment-level isolation and permissions
• Simplifies the promotion process between environments

Use LATEST Tag with Semantic Versioning

For most use cases, rely on the LATEST tag (or specify no tag, which defaults to LATEST). This automatically incorporates any changes that you deploy from your Prompt or Workflow Sandbox.

When you need more granular control, use Release Tags following semantic versioning conventions. Only use custom Release Tags when you need super fine-grained control over your deployment versions.

Environment Management

Creating and Configuring Environments

Environments can be created and managed through your Workspace Settings. Each environment provides:

• Isolated API key management
• Separate release histories
• Independent monitoring and observability data
• Scoped document indexes and search results

Environment Picker

Use the Environment picker at the top of the Vellum interface to switch between different environments. This picker controls:

• Which environment’s data you’re viewing
• Which environment’s releases you’re managing
• Which environment’s monitoring data is displayed
• Which environment’s API keys are being managed

Promoting Changes Between Environments

To promote changes from one environment to another:

1. Deploy your changes to the source environment (e.g., development)
2. Test and validate the changes in that environment
3. Use the same deployment in your target environment (e.g., staging)
4. Deploy the tested version using Release Tags for precise version control

This workflow ensures that you’re promoting exactly the same code and configuration that you’ve tested, reducing the risk of environment-specific issues.

Best Practices

Environment Naming

While Vellum doesn’t enforce specific environment names, we recommend following common conventions:

• Development: For active development and experimentation
• Staging: For pre-production testing and validation
• Production: For live, customer-facing deployments

API Key Management

• Use separate API keys for each environment
• Store API keys securely using environment variables or secret management systems
• Regularly rotate API keys, especially for production environments
• Never use production API keys in development or testing

Release Management

• Use descriptive Release Tags that follow semantic versioning
• Test thoroughly in development and staging before promoting to production
• Maintain clear documentation of what changes are included in each release
• Use the LATEST tag for most deployments to simplify your workflow

Monitoring and Observability

• Set up appropriate monitoring for each environment
• Use Environment-specific webhooks and integrations
• Monitor costs and usage patterns across environments
• Set up alerts for production environments

This approach provides better organization, reduces complexity, and takes full advantage of Environment-level isolation and permissions while maintaining the flexibility to manage releases according to your specific workflow requirements.