Skip to main content

​
Environment Overview

Helicone supports deploying different prompt versions to separate environments, enabling safe testing before production deployment.

​
Common Environment Setup

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Development │ →   │   Staging   │ →   │ Production  │
│   v2.3      │     │    v2.2     │     │    v2.0     │
└─────────────┘     └─────────────┘     └─────────────┘
Development: Test experimental changes Staging: QA and validation before production Production: Stable version serving live traffic You can create custom environments to match your workflow (e.g., qa, preview, canary).

​
Deploying to Environments

​
Set Environment for Version

Deploy a specific version to an environment: 
import { getJawnClient } from "./lib/clients/jawn";

const jawn = getJawnClient(orgId);

await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "your-prompt-id",
    promptVersionId: "version-to-deploy",
    environment: "production",
  },
});

​
Multiple Environments

A single version can be deployed to multiple environments: 
const environments = ["staging", "qa", "preview"];

for (const env of environments) {
  await jawn.POST("/v1/prompt-2025/update/environment", {
    body: {
      promptId: "your-prompt-id",
      promptVersionId: "version-id",
      environment: env,
    },
  });
}

​
Remove from Environment

await jawn.POST("/v1/prompt-2025/remove/environment", {
  body: {
    promptId: "your-prompt-id",
    promptVersionId: "version-id",
    environment: "staging",
  },
});

​
Loading Environment-Specific Prompts

​
Using the SDK

Load prompts based on your application environment: 
import { HeliconePromptManager } from "@helicone/prompts";

const manager = new HeliconePromptManager({
  apiKey: process.env.HELICONE_API_KEY!,
});

// Load from current environment
const { body } = await manager.getPromptBody({
  prompt_id: "customer-support",
  environment: process.env.NODE_ENV, // "development", "staging", "production"
  inputs: {
    customer_name: "Alice",
    issue_type: "billing",
  },
});

​
Fallback Strategy

If no version is deployed to the requested environment, you can implement fallback logic: 
async function getPromptWithFallback(
  promptId: string,
  environment: string,
  inputs: Record<string, any>
) {
  try {
    // Try environment-specific version
    return await manager.getPromptBody({
      prompt_id: promptId,
      environment,
      inputs,
    });
  } catch (error) {
    console.warn(`No version for ${environment}, falling back to production`);
    // Fallback to production
    return await manager.getPromptBody({
      prompt_id: promptId,
      environment: "production",
      inputs,
    });
  }
}

​
Query Environment Version

Check what version is deployed to an environment: 
const response = await jawn.POST("/v1/prompt-2025/query/environment-version", {
  body: {
    promptId: "your-prompt-id",
    environment: "production",
  },
});

const version = response.data?.data;
console.log(`Production is on v${version.major_version}.${version.minor_version}`);

​
Deployment Workflow

​
1. Create and Test Locally

// Create new version
const newVersion = await jawn.POST("/v1/prompt-2025/update", {
  body: {
    promptId: "my-prompt",
    promptVersionId: "current-version",
    newMajorVersion: false,
    commitMessage: "Improved response quality",
    promptBody: {
      // ... your prompt
    },
  },
});

// Deploy to development
await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "my-prompt",
    promptVersionId: newVersion.data?.data?.id!,
    environment: "development",
  },
});

​
2. Validate in Staging

// Promote to staging
await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "my-prompt",
    promptVersionId: newVersion.data?.data?.id!,
    environment: "staging",
  },
});

// Run integration tests against staging
const { body } = await manager.getPromptBody({
  prompt_id: "my-prompt",
  environment: "staging",
  inputs: testInputs,
});

// Verify outputs meet quality standards

​
3. Deploy to Production

// After validation, deploy to production
await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "my-prompt",
    promptVersionId: newVersion.data?.data?.id!,
    environment: "production",
  },
});

console.log("✅ Deployed to production");

​
4. Monitor and Rollback if Needed

If issues arise, quickly rollback: 
// Get previous production version
const versions = await jawn.POST("/v1/prompt-2025/query/versions", {
  body: { promptId: "my-prompt" },
});

const previousVersion = versions.data?.data?.find(
  (v) => v.environments?.includes("production-backup")
);

// Rollback
await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "my-prompt",
    promptVersionId: previousVersion!.id,
    environment: "production",
  },
});

​
Best Practices

​
Environment Configuration

Use environment variables to manage prompt loading: 
// config.ts
export const config = {
  promptEnvironment: process.env.PROMPT_ENV || process.env.NODE_ENV || "production",
  heliconeApiKey: process.env.HELICONE_API_KEY!,
};

// prompts.ts
const manager = new HeliconePromptManager({
  apiKey: config.heliconeApiKey,
});

export async function loadPrompt(promptId: string, inputs: Record<string, any>) {
  return await manager.getPromptBody({
    prompt_id: promptId,
    environment: config.promptEnvironment,
    inputs,
  });
}

​
Gradual Rollout

Implement canary deployments: 
const useCanary = Math.random() < 0.1; // 10% of traffic

const { body } = await manager.getPromptBody({
  prompt_id: "my-prompt",
  environment: useCanary ? "canary" : "production",
  inputs,
});

​
Version Tagging

Tag production versions before deploying new ones: 
// Before deploying v2.3 to production:
// 1. Get current production version (v2.2)
const currentProd = await jawn.POST("/v1/prompt-2025/query/environment-version", {
  body: { promptId: "my-prompt", environment: "production" },
});

// 2. Tag it as production-backup
await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "my-prompt",
    promptVersionId: currentProd.data?.data?.id!,
    environment: "production-backup",
  },
});

// 3. Deploy new version to production

​
List All Environments

const response = await jawn.GET("/v1/prompt-2025/environments", {
  params: {},
});

const environments = response.data?.data || [];
console.log("Available environments:", environments);

​
Deployment Checklist

  • Test new version in development environment
  • Run automated tests against staging
  • Review prompt changes with stakeholders
  • Tag current production version as backup
  • Deploy to production during low-traffic window
  • Monitor error rates and quality metrics
  • Keep rollback plan ready
  • Document changes in commit message

​
Next Steps

Versioning

Learn about version management

SDK Integration

Integrate prompts into your app