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.
Understanding what differs between Environments versus what remains consistent is crucial for effective Environment management in Vellum.
The following definitions are shared across all Environments within your Workspace:
Key Insight: When you create or modify a Prompt Sandbox or Workflow Sandbox, those changes are independent of the Environment. The sandbox definitions themselves are not environment-specific.
The following configuration and data are isolated per Environment:
Important: While Prompt and Workflow Sandboxes are shared definitions, their deployment release history is Environment-scoped. This means you can have different versions deployed in different Environments.
Here’s a concrete example of how this works:
This approach allows you to iterate on your prompts and workflows while maintaining strict control over what’s deployed in each Environment.
A common point of confusion is understanding how Prompt Sandboxes and Workflow Sandboxes behave when switching between Environments. Here’s what you need to know:
Runtime Behavior: While the sandbox definitions are identical across Environments, the runtime behavior of that Prompt/Workflow Sandbox may differ based on which Environment you have active, if that Prompt/Workflow references Environment Variables or Document Indexes.
Mental Model: Think of sandboxes as your “source code” and deployments as your “compiled applications.” The source code is shared, but you can compile and deploy different versions to different Environments.
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.
Environment Picker: Look for the Environment picker at the top of the Vellum interface to see which Environment context you’re currently working in and to switch between different Environments.
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=workspaces&workspace-settings-tab=environments
API Key Management: Navigate to Workspace Settings to manage your Environment-specific API keys. Each Environment maintains its own separate set of API keys for proper isolation.
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.
Sandbox vs Deployment Relationship: While your Prompt Sandboxes and Workflow Sandboxes are the same across Environments, each Environment maintains its own deployment release history. This means:
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.
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.
Environment Variables allow you to configure variables whose values are different based on the Environment in which they’re used. This is particularly useful for managing configuration values like API keys, endpoints, or other settings that need to vary between development, staging, and production Environments.
A common use case is having an API Node in a Vellum Workflow that connects to an external service like the Firecrawl API. You might want to use one API key when the Workflow is run within your Development Environment and a different API key when the Workflow is run in Production.
To create an Environment Variable:
CAPITALIZED_SNAKE_CASE format)
When creating an Environment Variable, you can specify its value within each Environment. The value can be configured in two ways:
Variable Naming: Environment Variable names must be in snake_case format and cannot be changed after creation. Choose descriptive names that clearly indicate the variable’s purpose.
Once defined, Environment Variables can be referenced as Node inputs in Workflows. The variable’s value is automatically determined by whichever Environment you have active when the Workflow executes.
Environment Variables appear in the input selection dropdown under the Environment Variable section, making them easily accessible when configuring Node inputs.
FIRECRAWL_API_KEY, DATABASE_URL)SERVICE_NAME_API_KEY)For optimal organization and workflow management, we recommend:
Instead of creating separate deployments for each Environment, use a single deployment and leverage Environments for isolation. This approach:
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.
Environments can be created and managed through your Workspace Settings. Each Environment provides:
Use the Environment picker at the top of the Vellum interface to switch between different Environments. This picker controls:
Vellum provides two primary methods for moving changes between Environments:
The most efficient way to promote tested changes is using the Release Promotion feature:
This creates a new Release in each selected Environment with the exact same configuration that you tested, ensuring consistency and reducing deployment risk.
For initial deployments or when you want to deploy to multiple Environments simultaneously:
This approach is useful when you want to push updates to Development and Staging simultaneously, or when setting up new deployments across multiple Environments.
Both methods ensure that you’re promoting exactly the same code and configuration that you’ve tested, reducing the risk of Environment-specific issues.
While Vellum doesn’t enforce specific Environment names, we recommend following common conventions:
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.