.env.example

# =============================================================================
# CHUK MCP Runtime - Environment Configuration
# =============================================================================
# Copy this file to .env and uncomment/modify the settings you need.
# The runtime automatically loads .env from the project root.
#
# Quick Start:
#   - No configuration needed for development (uses memory storage)
#   - For deployment, configure storage + session providers below
# =============================================================================

# =============================================================================
# ENVIRONMENT VARIABLES REFERENCE
# =============================================================================
# This section lists ALL available variables organized by provider.
# Scroll down for complete configuration examples.
#
# STORAGE PROVIDERS:
#
# ┌─────────────┬──────────────────────────────────┬──────────┬─────────┐
# │ Provider    │ Variable                         │ Required │ Default │
# ├─────────────┼──────────────────────────────────┼──────────┼─────────┤
# │ MEMORY      │ ARTIFACT_STORAGE_PROVIDER=memory │ No       │ memory  │
# │             │ ARTIFACT_SESSION_PROVIDER=memory │ No       │ memory  │
# │             │                                  │          │         │
# │ FILESYSTEM  │ ARTIFACT_STORAGE_PROVIDER=filesystem │ Yes  │ -       │
# │             │ ARTIFACT_SESSION_PROVIDER=memory │ No       │ memory  │
# │             │ ARTIFACT_FS_ROOT=./artifacts     │ No       │ ./artifacts │
# │             │ ARTIFACT_BUCKET=local-artifacts  │ No       │ artifacts │
# │             │                                  │          │         │
# │ S3          │ ARTIFACT_STORAGE_PROVIDER=s3     │ Yes      │ -       │
# │ (AWS/Tigris)│ ARTIFACT_BUCKET=my-bucket        │ Yes      │ -       │
# │ (MinIO)     │ AWS_ACCESS_KEY_ID=...            │ Yes      │ -       │
# │             │ AWS_SECRET_ACCESS_KEY=...        │ Yes      │ -       │
# │             │ AWS_REGION=us-east-1             │ No       │ us-east-1 │
# │             │ S3_ENDPOINT_URL=https://...      │ No*      │ AWS S3  │
# │             │ ARTIFACT_SESSION_PROVIDER=redis  │ No       │ memory  │
# │             │ *Required for non-AWS S3         │          │         │
# │             │                                  │          │         │
# │ IBM_COS     │ Method 1: S3-Compatible (HMAC) - RECOMMENDED         │
# │ (S3-compat) │ ARTIFACT_STORAGE_PROVIDER=s3     │ Yes      │ -       │
# │             │ ARTIFACT_BUCKET=my-bucket        │ Yes      │ -       │
# │             │ S3_ENDPOINT_URL=https://s3.us-south... │ Yes  │ -       │
# │             │ AWS_ACCESS_KEY_ID=...            │ Yes      │ -       │
# │             │ AWS_SECRET_ACCESS_KEY=...        │ Yes      │ -       │
# │             │ AWS_REGION=us-south              │ No       │ us-east-1 │
# │             │                                  │          │         │
# │ IBM_COS     │ Method 2: Native IAM Credentials │          │         │
# │ (IAM)       │ ARTIFACT_STORAGE_PROVIDER=ibm_cos│ Yes      │ -       │
# │             │ ARTIFACT_BUCKET=my-bucket        │ Yes      │ -       │
# │             │ IBM_COS_ENDPOINT=https://...     │ Yes      │ -       │
# │             │ IBM_COS_APIKEY=...               │ Yes      │ -       │
# │             │ IBM_COS_INSTANCE_CRN=crn:v1...   │ Yes      │ -       │
# └─────────────┴──────────────────────────────────┴──────────┴─────────┘
#
# SESSION PROVIDERS (for metadata caching):
#
# ┌─────────────┬──────────────────────────────────┬──────────┬─────────┐
# │ Provider    │ Variable                         │ Required │ Default │
# ├─────────────┼──────────────────────────────────┼──────────┼─────────┤
# │ MEMORY      │ ARTIFACT_SESSION_PROVIDER=memory │ No       │ memory  │
# │             │                                  │          │         │
# │ REDIS       │ ARTIFACT_SESSION_PROVIDER=redis  │ Yes      │ -       │
# │             │ REDIS_URL=redis://localhost:6379/0│ Yes     │ -       │
# │             │ REDIS_TLS_INSECURE=1             │ No       │ 0       │
# └─────────────┴──────────────────────────────────┴──────────┴─────────┘
#
# COMMON SETTINGS (all providers):
#
# ┌──────────────────────────────┬──────────────────────────────────┬─────────┐
# │ Variable                     │ Purpose                          │ Default │
# ├──────────────────────────────┼──────────────────────────────────┼─────────┤
# │ ARTIFACT_BUCKET              │ Bucket/container name            │ artifacts│
# │ ARTIFACT_METADATA_TTL        │ Metadata cache TTL (seconds)     │ 900     │
# │ ARTIFACT_PRESIGN_EXPIRES     │ Presigned URL expiry (seconds)   │ 3600    │
# │ MCP_SANDBOX_ID               │ Sandbox identifier               │ auto    │
# │ SESSION_TTL_HOURS            │ Session lifetime (hours)         │ 24      │
# └──────────────────────────────┴──────────────────────────────────┴─────────┘

# =============================================================================
# STORAGE PROVIDER - Where artifact files are stored
# =============================================================================
# Options: memory | filesystem | s3 | ibm_cos
# Default: memory (if not specified)

# ─────────────────────────────────────────────────────────────────────────────
# Option 1: MEMORY (Default - Development)
# ─────────────────────────────────────────────────────────────────────────────
# Stores files in RAM - fast, ephemeral, no setup required
# Perfect for: Development, testing, demos
# Pros: Zero configuration, instant setup, fast
# Cons: Data lost on restart, limited by RAM
#
# ARTIFACT_STORAGE_PROVIDER=memory
# ARTIFACT_SESSION_PROVIDER=memory

# ─────────────────────────────────────────────────────────────────────────────
# Option 2: FILESYSTEM (Development/Testing)
# ─────────────────────────────────────────────────────────────────────────────
# Stores files on local disk
# Perfect for: Local development, single-server deployments, debugging
# Pros: Persistent, inspectable, no external dependencies
# Cons: Not suitable for multi-server deployments, limited scalability
#
# ARTIFACT_STORAGE_PROVIDER=filesystem
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_FS_ROOT=./artifacts
# ARTIFACT_BUCKET=local-artifacts

# ─────────────────────────────────────────────────────────────────────────────
# Option 3: AWS S3 (Production)
# ─────────────────────────────────────────────────────────────────────────────
# Stores files in AWS S3 or S3-compatible storage (Tigris, MinIO, etc.)
# Perfect for: Production, multi-server deployments, cloud-native apps
# Pros: Scalable, durable (11 nines), multi-region, versioning support
# Cons: Requires AWS account, costs per GB
#
# --- AWS S3 ---
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=redis  # Recommended for distributed deployments
# ARTIFACT_BUCKET=my-mcp-artifacts
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...
# # S3_ENDPOINT_URL=https://s3.amazonaws.com  # Optional, defaults to AWS
#
# --- Tigris (S3-compatible, on Fly.io) ---
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_BUCKET=my-bucket
# AWS_REGION=auto
# S3_ENDPOINT_URL=https://fly.storage.tigris.dev
# AWS_ENDPOINT_URL_S3=https://fly.storage.tigris.dev
# AWS_ACCESS_KEY_ID=tid_...
# AWS_SECRET_ACCESS_KEY=tsec_...
#
# --- MinIO (S3-compatible, self-hosted) ---
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_BUCKET=mcp-artifacts
# AWS_REGION=us-east-1
# S3_ENDPOINT_URL=http://localhost:9000
# AWS_ACCESS_KEY_ID=minioadmin
# AWS_SECRET_ACCESS_KEY=minioadmin

# ─────────────────────────────────────────────────────────────────────────────
# Option 4: IBM CLOUD OBJECT STORAGE (Enterprise)
# ─────────────────────────────────────────────────────────────────────────────
# Stores files in IBM Cloud Object Storage (COS)
# Perfect for: Enterprise deployments, compliance requirements, IBM Cloud users
# Pros: Enterprise SLA, compliance certs (GDPR/HIPAA/SOC2), immutable storage
# Cons: Requires IBM Cloud account, enterprise pricing
#
# IBM COS supports TWO authentication methods:
#
# Method 1: S3-Compatible (HMAC) Credentials - RECOMMENDED
# (This is what you get from IBM COS "Service Credentials" with HMAC enabled)
ARTIFACT_STORAGE_PROVIDER=s3
ARTIFACT_SESSION_PROVIDER=memory
ARTIFACT_BUCKET=my-cos-bucket
S3_ENDPOINT_URL=https://s3.us-south.cloud-object-storage.appdomain.cloud
AWS_ACCESS_KEY_ID=my_access_key_id
AWS_SECRET_ACCESS_KEY=my_secret_access_key_id
AWS_REGION=us-south
#
# Method 2: Native IAM Credentials (API Key)
# ARTIFACT_STORAGE_PROVIDER=ibm_cos
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_BUCKET=my-cos-bucket
# IBM_COS_ENDPOINT=https://s3.us-south.cloud-object-storage.appdomain.cloud
# IBM_COS_APIKEY=my_api_key
# IBM_COS_INSTANCE_CRN=my_instance_crn

# =============================================================================
# SESSION PROVIDER - Where artifact metadata/sessions are cached
# =============================================================================
# Options: memory | redis
# Default: memory (if not specified)

# Memory (Default)
# ARTIFACT_SESSION_PROVIDER=memory

# Redis (Recommended for Production)
# ARTIFACT_SESSION_PROVIDER=redis
# REDIS_URL=redis://localhost:6379/0
# # REDIS_TLS_INSECURE=1  # Set to 1 to disable SSL cert verification

# =============================================================================
# ARTIFACT CONFIGURATION
# =============================================================================
# Common settings for all storage providers

# Bucket/container name (required for s3/ibm_cos)
ARTIFACT_BUCKET=mcp-artifacts

# Metadata TTL (how long to cache file metadata, default: 900 seconds = 15 min)
# ARTIFACT_METADATA_TTL=900

# Presigned URL expiry (for download links, default: 3600 seconds = 1 hour)
# ARTIFACT_PRESIGN_EXPIRES=3600

# =============================================================================
# EXAMPLE CONFIGURATIONS BY USE CASE
# =============================================================================

# ─────────────────────────────────────────────────────────────────────────────
# Local Development (Default)
# ─────────────────────────────────────────────────────────────────────────────
# No configuration needed! Just use memory storage (default).
# Files stored in RAM, sessions in RAM. Perfect for quick iteration.

# ─────────────────────────────────────────────────────────────────────────────
# Local Development with Persistence
# ─────────────────────────────────────────────────────────────────────────────
# ARTIFACT_STORAGE_PROVIDER=filesystem
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_FS_ROOT=./artifacts
# ARTIFACT_BUCKET=local-dev

# ─────────────────────────────────────────────────────────────────────────────
# Testing/Staging with S3
# ─────────────────────────────────────────────────────────────────────────────
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=memory
# ARTIFACT_BUCKET=staging-mcp-artifacts
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...

# ─────────────────────────────────────────────────────────────────────────────
# Production with S3 + Redis
# ─────────────────────────────────────────────────────────────────────────────
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=redis
# ARTIFACT_BUCKET=prod-mcp-artifacts
# AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...
# REDIS_URL=rediss://prod-redis:6379/0
# ARTIFACT_METADATA_TTL=1800
# ARTIFACT_PRESIGN_EXPIRES=7200

# ─────────────────────────────────────────────────────────────────────────────
# Production with IBM COS + Redis (Enterprise)
# ─────────────────────────────────────────────────────────────────────────────
# ARTIFACT_STORAGE_PROVIDER=s3
# ARTIFACT_SESSION_PROVIDER=redis
# ARTIFACT_BUCKET=prod-mcp-artifacts
# S3_ENDPOINT_URL=https://s3.us-south.cloud-object-storage.appdomain.cloud
# AWS_ACCESS_KEY_ID=<your-hmac-access-key>
# AWS_SECRET_ACCESS_KEY=<your-hmac-secret-key>
# AWS_REGION=us-south
# REDIS_URL=rediss://prod-redis:6379/0
# ARTIFACT_METADATA_TTL=1800
# ARTIFACT_PRESIGN_EXPIRES=7200

# =============================================================================
# MCP SERVER CONFIGURATION (Optional)
# =============================================================================
# Additional settings for the MCP server

# Sandbox ID (used for multi-tenant isolation)
# MCP_SANDBOX_ID=sandbox-001

# Session TTL (how long sessions live, default: 24 hours)
# SESSION_TTL_HOURS=24

# =============================================================================
# ADDITIONAL SETTINGS
# =============================================================================

# GitHub Personal Access Token (for GitHub integrations)
# GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

# Logging level (DEBUG, INFO, WARNING, ERROR)
# LOG_LEVEL=INFO