OpenEvidence Multi-Environment Setup Skill

OpenEvidence Multi-Environment Setup

Overview

OpenEvidence clinical AI requires strict environment separation to maintain HIPAA compliance across the data lifecycle. Development uses only synthetic patient data with no PHI access, staging operates on de-identified datasets for clinical validation, and production handles full PHI under BAA-covered infrastructure. Each environment enforces its own audit logging, encryption, and access control policies. Misconfigured environments risk PHI exposure and regulatory violations, making environment validation a hard requirement at startup.

Environment Configuration

const openEvidenceConfig = (env: string) => ({
  development: {
    apiKey: process.env.OPENEVIDENCE_API_KEY_DEV!, baseUrl: "https://api.dev.openevidence.com/v1",
    dataClassification: "synthetic", phiEnabled: false, auditLevel: "basic", encryptionRequired: false,
  },
  staging: {
    apiKey: process.env.OPENEVIDENCE_API_KEY_STG!, baseUrl: "https://api.staging.openevidence.com/v1",
    dataClassification: "de-identified", phiEnabled: false, auditLevel: "full", encryptionRequired: true,
  },
  production: {
    apiKey: process.env.OPENEVIDENCE_API_KEY_PROD!, baseUrl: "https://api.openevidence.com/v1",
    dataClassification: "phi", phiEnabled: true, auditLevel: "full", encryptionRequired: true,
  },
}[env]);

Environment Files

# Per-env files: .env.development, .env.staging, .env.production
OPENEVIDENCE_API_KEY_{DEV|STG|PROD}=<api-key>
OPENEVIDENCE_BASE_URL=https://api.{dev.|staging.|""}openevidence.com/v1
OPENEVIDENCE_DATA_CLASS={synthetic|de-identified|phi}
OPENEVIDENCE_PHI_ENABLED={false|false|true}
OPENEVIDENCE_AUDIT_LEVEL={basic|full|full}
OPENEVIDENCE_BAA_ID=<baa-id>          # production only

Environment Validation

function validateOpenEvidenceEnv(env: string): void {
  const suffix = { development: "_DEV", staging: "_STG", production: "_PROD" }[env];
  const required = [`OPENEVIDENCE_API_KEY${suffix}`, "OPENEVIDENCE_BASE_URL", "OPENEVIDENCE_DATA_CLASS"];
  if (env === "production") required.push("OPENEVIDENCE_BAA_ID");
  if (env !== "development") required.push("OPENEVIDENCE_AUDIT_LEVEL");
  const missing = required.filter((k) => !process.env[k]);
  if (missing.length) throw new Error(`Missing OpenEvidence vars for ${env}: ${missing.join(", ")}`);
  if (env === "production" && process.env.OPENEVIDENCE_PHI_ENABLED !== "true")
    throw new Error("HIPAA violation: PHI must be enabled in production");
}

Promotion Workflow

# 1. Run clinical queries against synthetic data in dev
curl -X POST "$OPENEVIDENCE_BASE_URL/query" \
  -H "Authorization: Bearer $OPENEVIDENCE_API_KEY_DEV" -d @synthetic-query.json

# 2. Validate with de-identified data in staging (audit logs required)
curl -X POST "$OPENEVIDENCE_BASE_URL/query" \
  -H "Authorization: Bearer $OPENEVIDENCE_API_KEY_STG" -d @staging-query.json

# 3. Verify HIPAA audit trail exists for all staging queries
curl "$OPENEVIDENCE_BASE_URL/audit/logs?env=staging" \
  -H "Authorization: Bearer $OPENEVIDENCE_API_KEY_STG" | jq '.totalEntries'

# 4. Deploy to production (requires BAA verification)
OPENEVIDENCE_BAA_ID=baa-2026-001 npm run deploy -- --env production --hipaa-check

Environment Matrix

| Setting | Dev | Staging | Prod | |---------|-----|---------|------| | Data Type | Synthetic only | De-identified | Full PHI | | PHI Access | No | No | Yes (BAA required) | | Audit Logging | Basic | Full | Full + HIPAA trail | | Encryption at Rest | Optional | Required | Required (AES-256) | | Access Control | Developer only | Clinical QA team | Authorized clinicians | | BAA Required | No | No | Yes |

Error Handling

| Issue | Cause | Fix | |-------|-------|-----| | HIPAA validation failed at startup | PHI_ENABLED not set in production | Set OPENEVIDENCE_PHI_ENABLED=true in prod env file | | BAA ID missing | Production deploy without BAA reference | Add OPENEVIDENCE_BAA_ID from compliance team | | 403 on PHI endpoint | Dev/staging key used against prod API | Use environment-specific API key with correct scope | | Audit log gap detected | Staging queries not logged | Verify OPENEVIDENCE_AUDIT_LEVEL=full in staging env |

Resources

OpenEvidence Docs

Next Steps

See openevidence-deploy-integration.

Agent Skills: OpenEvidence Multi-Environment Setup

Install this agent skill to your local

Skill Files