Juicebox Multi-Environment Setup

Overview

Juicebox AI analysis requires environment separation to enforce workspace isolation, control data access, and prevent accidental exports of sensitive datasets. Development works with sample datasets and strict result limits for fast iteration, staging connects to full production data but disables export functionality, and production enables all features with full export capabilities. Each environment uses isolated workspaces so analysis experiments in dev never affect production workspace state or user-facing reports.

Environment Configuration

const juiceboxConfig = (env: string) => ({
  development: {
    apiKey: process.env.JB_KEY_DEV!, baseUrl: "https://api.dev.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_DEV!, resultLimit: 5, exportEnabled: false,
  },
  staging: {
    apiKey: process.env.JB_KEY_STG!, baseUrl: "https://api.staging.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_STG!, resultLimit: 20, exportEnabled: false,
  },
  production: {
    apiKey: process.env.JB_KEY_PROD!, baseUrl: "https://api.juicebox.work/v1",
    workspaceId: process.env.JB_WORKSPACE_PROD!, resultLimit: 50, exportEnabled: true,
  },
}[env]);

Environment Files

# Per-env files: .env.development, .env.staging, .env.production
JB_KEY_{DEV|STG|PROD}=<api-key>
JB_WORKSPACE_{DEV|STG|PROD}=<workspace-id>
JB_BASE_URL=https://api.{dev.|staging.|""}juicebox.work/v1
JB_EXPORT_ENABLED={false|false|true}
JB_DATASET_SCOPE={sample|full|full}

Environment Validation

function validateJuiceboxEnv(env: string): void {
  const suffix = { development: "_DEV", staging: "_STG", production: "_PROD" }[env];
  const required = [`JB_KEY${suffix}`, `JB_WORKSPACE${suffix}`, "JB_BASE_URL"];
  const missing = required.filter((k) => !process.env[k]);
  if (missing.length) throw new Error(`Missing Juicebox vars for ${env}: ${missing.join(", ")}`);
}

Promotion Workflow

# 1. Run analysis queries against sample data in dev
curl -X POST "$JB_BASE_URL/analyze" \
  -H "Authorization: Bearer $JB_KEY_DEV" -d @test-query.json

# 2. Validate same queries against full dataset in staging (exports blocked)
curl -X POST "$JB_BASE_URL/analyze" \
  -H "Authorization: Bearer $JB_KEY_STG" -d @test-query.json | jq '.resultCount'

# 3. Verify workspace isolation — staging results don't appear in prod
curl "$JB_BASE_URL/workspaces/$JB_WORKSPACE_PROD/reports" \
  -H "Authorization: Bearer $JB_KEY_PROD" | jq 'length'

# 4. Deploy to production with export capabilities enabled
JB_EXPORT_ENABLED=true npm run deploy -- --env production

Environment Matrix

Error Handling

Prerequisites

• Approved environment boundaries, sandbox-only synthetic fixtures, secret references rather than literal keys, source/destination allowlists, suppression controls, and a tested rollback revision.

Instructions

1. Keep development and staging datasets synthetic; reject cross-environment credentials, sources, destinations, and real-record exports.
2. Run deployment probes with aggregate metrics only and confirm suppression, data minimization, and contacts_exported=0 before promotion.
3. Release through one sandbox canary, monitor quota and policy drift, and stop immediately on scope, retention, or authorization failures.
4. Promote only after owner approval; restore the prior revision, revoke temporary access, and delete staged fixtures if validation fails.

Output

Produce an environment receipt with environment-to-workspace mapping, fixture type, source/destination approval, suppression and no-export assertions, canary outcome, approver, retention/deletion proof, and rollback reference. Exclude keys and contact-level data.

Examples

env=staging; workspace=isolated-synthetic; source=approved; destination=none; suppression=pass; contacts_exported=0; rollback=release-r31 is safe to promote for approval.

Resources

• Juicebox Docs
• Juicebox API Reference

Next Steps

See juicebox-deploy-integration.