Configuration

Configure Orchestrated to work with your environment, cloud services, and team setup.

Configuration Overview

Orchestrated supports multiple configuration methods with the following priority:

Code - Directly passed parameters (highest priority)
Environment Variables - ORCHESTRATED_* environment variables
Config File - Orchestrated.yaml in your project root
Defaults - Built-in default values (lowest priority)

Config File

Create an Orchestrated.yaml file in your project root for centralized configuration:

# API Gateway endpoint (optional)
apiUrl: https://api.getorchestrated.com

# Tenant identifier (REQUIRED)
tenantId: your-tenant-id

# Service name (REQUIRED)
serviceName: your-service-name

# Environment (optional, default: development)
environment: production

# S3 configuration (REQUIRED for orcha upload)
s3Bucket: your-bucket-name
s3Region: us-east-1
# s3Endpoint: https://custom-s3.example.com  # Optional

Required Fields

tenantId - Your organization's tenant identifier for multi-tenancy
serviceName - Service name for filtering and organizing evaluations
s3Bucket - S3 bucket name (required for orcha upload command)

Optional Fields

apiUrl - Custom API endpoint (defaults to production)
environment - Environment name (development, staging, production)
s3Region - AWS region (defaults to us-east-1)
s3Endpoint - Custom S3-compatible endpoint

Environment Variables

All configuration values can be set via environment variables:

State Configuration

ORCHESTRATED_API_URL           # API Gateway endpoint
ORCHESTRATED_TENANT_ID         # Tenant identifier (REQUIRED)
ORCHESTRATED_SERVICE_NAME      # Service name (REQUIRED)
ORCHESTRATED_ACCESS_TOKEN      # Cognito access token
ORCHESTRATED_ENVIRONMENT       # Environment name
ORCHESTRATED_APP_URL           # Web console URL
ORCHESTRATED_APP_CLIENT_ID     # Cognito client ID
ORCHESTRATED_S3_BUCKET         # S3 bucket (REQUIRED for upload)
ORCHESTRATED_S3_REGION         # S3 region
ORCHESTRATED_S3_ENDPOINT       # S3 endpoint (optional)

AWS Credentials

AWS_ACCESS_KEY_ID              # AWS access key for S3 uploads
AWS_SECRET_ACCESS_KEY          # AWS secret key for S3 uploads

Other Variables

OPENAI_API_KEY                 # For autoevals scorers
ORCHA_VERBOSE=true             # Verbose logging (CLI)
ORCHA_JSONL=true               # JSONL output (CLI)

State Management

Orchestrated uses global state for configuration values. State is automatically initialized from your config file and environment variables.

Initialization

import { initState, getState } from 'orchestrated'

// Initialize with config file + env vars
await initState()

// Or initialize with explicit values
await initState({
  tenantId: "acme",
  serviceName: "production",
  environment: "production",
})

// Access state
const state = getState()
console.log(state.tenantId)
console.log(state.environment)

Auto-injection into Context

State is automatically available in your evaluation context:

await Eval("My Eval", {
  task: async (input, ctx) => {
    // Access state via ctx.state
    const tenant = ctx.state.tenantId
    const env = ctx.state.environment
    // ...
  },
  scores: ["Effectiveness"]
})

Authentication

Orchestrated uses AWS Cognito for authentication. Credentials are stored in ~/.orcha/credentials.json after login.

Login via CLI

orcha login

This opens a browser window for authentication. Once complete, credentials are saved locally.

Check Authentication

orcha whoami

Displays your current user, token status, and configuration.

Logout

orcha logout

Clears stored credentials.

Manual Token

You can also set the access token directly:

export ORCHESTRATED_ACCESS_TOKEN="your-token-here"

Or in your config file (not recommended for production):

await initState({
  accessToken: "your-token-here"
})

Quick Start Guide State Management API