env.example

# Cloud API Configuration via Environment Variables
# Copy this file to .env and fill in your actual values

# =============================================================================
# Server Configuration
# =============================================================================
SERVER_HOST=0.0.0.0
SERVER_PORT=3000
# Interval between scheduled-pricing-change apply passes (seconds, 0 = disabled)
PRICING_CHANGE_APPLY_INTERVAL_SECS=60
# Interval between usage_hourly aggregate ticks (seconds, 0 = disabled)
# Nightly parity checks require the default 3600-second cadence.
USAGE_HOURLY_INTERVAL_SECS=3600

# =============================================================================
# Model Discovery Configuration
# =============================================================================
# URL of the model discovery server
MODEL_DISCOVERY_SERVER_URL=http://localhost:8080/models

# API key for authenticating with discovered model providers
MODEL_DISCOVERY_API_KEY=YOUR_API_KEY_HERE

# Shared service-token accepted by `POST /v1/internal/usage` for trusted
# reporters (e.g. inference-proxy). Set the SAME value here and on every
# inference-proxy CVM (their env var is also `CLOUD_API_USAGE_TOKEN`).
# Leave unset to disable the endpoint (it returns 503 and reporters fall
# back to the legacy `POST /v1/usage` + `sk-…` path).
# CLOUD_API_USAGE_TOKEN=

# Password of the placement Valkey `router` ACL user (secret; or a file path
# via PLACEMENT_REDIS_PASSWORD_FILE). Enables smart placement together with
# PLACEMENT_REDIS_HOST below; also keys the affinity/pin HMACs, so every
# cloud-api node must use the same value. Leave unset: no placement state,
# all routing is legacy.
# PLACEMENT_REDIS_PASSWORD=

# Placement Valkey endpoint (not secret). Without PLACEMENT_REDIS_HOST, or with
# an invalid value below, placement stays off (logged once at startup) and all
# routing is legacy. With TLS (the default) the host must match the server
# certificate's SAN, so use the Valkey's Elastic IP, and the CA that signed it
# is required: PEM inline (a single line with literal \n escapes is accepted),
# or a file path via PLACEMENT_REDIS_TLS_CA_CERT_FILE. A CA that does not parse
# turns placement off. TLS_ENABLED=false sends the password in plaintext.
# PLACEMENT_REDIS_HOST=203.0.113.7
# PLACEMENT_REDIS_PORT=6379
# PLACEMENT_REDIS_TLS_ENABLED=true
# PLACEMENT_REDIS_TLS_CA_CERT_FILE=/run/certs/placement-valkey-ca.pem
# PLACEMENT_REDIS_TLS_CA_CERT="-----BEGIN CERTIFICATE-----
# ...
# -----END CERTIFICATE-----"

# How often to refresh model list (in seconds)
MODEL_DISCOVERY_REFRESH_INTERVAL=300

# Discovery request timeout (in seconds)
MODEL_DISCOVERY_TIMEOUT=5

# Model inference timeout (in seconds) - set to 30 minutes for large models
MODEL_INFERENCE_TIMEOUT=18000

# E2EE backend-key affinity is enabled by default. Set to 0 or false to
# restore pre-affinity routing during rollback.
E2EE_BACKEND_KEY_AFFINITY=true

# =============================================================================
# Logging Configuration
# =============================================================================
# Global log level: trace, debug, info, warn, error
LOG_LEVEL=info

# Log format: json, compact, pretty
# Use 'json' for containerized environments with Datadog agent
# Use 'compact' for local development
# Use 'pretty' for debugging
LOG_FORMAT=json

# Module-specific log levels (optional)
LOG_MODULE_API=info
LOG_MODULE_SERVICES=info

# =============================================================================
# DStack Client Configuration
# =============================================================================
DSTACK_CLIENT_URL=http://localhost:8000

# =============================================================================
# Authentication Configuration
# =============================================================================
# Set to true to use mock authentication (development only)
AUTH_MOCK=false

# Set for JWT access token encoding
AUTH_ENCODING_KEY=YOUR_AUTH_ENCODING_KEY

# Reject session access tokens without a `sid` (session id) claim.
# Access tokens are bound to their refresh-token session and are invalidated
# when that session is revoked (logout). Legacy tokens issued before session
# binding carry no `sid` and cannot be checked against a live session.
# Default false: legacy tokens keep validating until they expire naturally.
# Set to true after one access-token lifetime has passed since deploying
# session binding, to reject any token that cannot be tied to a live session.
AUTH_REQUIRE_SESSION_BOUND_ACCESS_TOKENS=false

# GitHub OAuth Configuration
# To set up:
# 1. Go to https://github.com/settings/developers
# 2. Create a new OAuth App
# 3. Set Authorization callback URL to: http://your-domain:3000/v1/auth/callback
# 4. Copy Client ID and Client Secret here
GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
GITHUB_REDIRECT_URL=http://localhost:3000/v1/auth/callback

# Google OAuth Configuration
# To set up:
# 1. Go to https://console.cloud.google.com/apis/credentials
# 2. Create OAuth 2.0 Client ID
# 3. Add authorized redirect URI: http://your-domain:3000/v1/auth/callback
# 4. Copy Client ID and Client Secret here
GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
GOOGLE_REDIRECT_URL=http://localhost:3000/v1/auth/callback

# NEAR OAuth Configuration
NEAR_EXPECTED_RECIPIENT=cloud.near.ai

# Admin Configuration
# Comma-separated list of email domains that are granted admin access
# Example: near.ai,admin.org
AUTH_ADMIN_DOMAINS=near.ai
# Enable read-only admin token issuance only after permission enforcement is deployed fleet-wide.
AUTH_ADMIN_READ_ONLY_TOKENS_ENABLED=false

# =============================================================================
# Database Configuration
# =============================================================================
# Connection mode: exactly "patroni" (default) or "direct".
# Keep "patroni" for existing deployments and the local postgres-test path.
DATABASE_CONNECTION_MODE=patroni

# Primary app ID for Patroni/PostgreSQL cluster discovery
# Use "postgres-test" for simple postgres connection without Patroni
# Database initialization in direct mode does not require this setting.
POSTGRES_PRIMARY_APP_ID=postgres-test

# Gateway subdomain for Patroni discovery (only used in production with Patroni)
GATEWAY_SUBDOMAIN=localhost

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=platform_api
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
# Optional mounted password file; takes precedence over DATABASE_PASSWORD.
# DATABASE_PASSWORD_FILE=/run/secrets/database-password
DATABASE_MAX_CONNECTIONS=5

# False is supported by the legacy local postgres-test path, not direct mode.
# Direct mode requires true and verifies the server certificate and hostname.
DATABASE_TLS_ENABLED=false

# Optional CA bundle path inside the application container.
# Direct mode uses platform trust if omitted; it may not include the RDS CA.
# DATABASE_TLS_CA_CERT_PATH=path/to/ca-certificate.crt

# RDS: replace the settings above with these values; see docs/rds-database.md.
# Use the actual writer endpoint and a separately provisioned application user.
# Mount the password file and official AWS regional CA bundle read-only.
# DATABASE_CONNECTION_MODE=direct
# DATABASE_HOST=your-instance.region.rds.amazonaws.com
# DATABASE_PORT=5432
# DATABASE_NAME=platform_api
# DATABASE_USERNAME=cloud_api_app
# DATABASE_PASSWORD_FILE=/run/secrets/rds-app-password
# DATABASE_TLS_ENABLED=true
# DATABASE_TLS_CA_CERT_PATH=/run/certs/us-east-1-bundle.pem

# Database migration SQL files directory (optional, for custom migration files path)
# DATABASE_MIGRATIONS_PATH=path/to/migrations/sql/directory

# =============================================================================
# Programmatic Usage Reporting
# =============================================================================
# Keep disabled until the six out-of-band indexes pass the rollout checks in
# docs/usage-reporting-rollout.md. Startup refuses to enable reporting if any
# required index is missing, invalid, or not ready.
USAGE_REPORTING_ENABLED=false
USAGE_REPORTING_GLOBAL_REQUESTS_PER_MINUTE=600
USAGE_REPORTING_TOKEN_REQUESTS_PER_MINUTE=60
USAGE_REPORTING_MAX_CONCURRENT_REQUESTS=4
USAGE_REPORTING_TOKEN_MAX_CONCURRENT_REQUESTS=2
USAGE_REPORTING_REQUEST_TIMEOUT_SECONDS=15

# =============================================================================
# Credit allocation
# =============================================================================
# Posting-time funding priority. Use each API/database credit type exactly once.
# Changing the order affects only new usage; increment the policy version with
# every semantic change so saved allocations remain auditable.
CREDIT_USAGE_ORDER=grant,staking_farm,transfer,payment,postpay
CREDIT_ALLOCATION_POLICY_VERSION=v2

# =============================================================================
# AWS S3 Configuration (for file uploads)
# =============================================================================
# S3 bucket name for file storage
AWS_S3_BUCKET=your-bucket-name

# AWS S3 region
AWS_S3_REGION=us-east-1

# AWS credentials (alternatively, use AWS CLI/environment credentials)
# AWS_ACCESS_KEY_ID=your-access-key-id
# AWS_SECRET_ACCESS_KEY=your-secret-access-key

# S3 Encryption Key Configuration
# Encryption key for files stored in S3 (must be 256-bit / 32 bytes, hex-encoded)
# Generate a key: openssl rand -hex 32
# Use either S3_ENCRYPTION_KEY or S3_ENCRYPTION_KEY_FILE (mounted secret in production)
S3_ENCRYPTION_KEY=your-hex-encoded-256-bit-encryption-key
# S3_ENCRYPTION_KEY_FILE=/path/to/encryption-key-file

# Enable only after every Cloud API instance has dual-read support and the
# operational database-encryption worker is ready to run.
DB_ENCRYPTION_WRITE_ENABLED=false
# Dedicated database key; do not reuse S3_ENCRYPTION_KEY.
DB_ENCRYPTION_KEY=your-hex-encoded-256-bit-database-encryption-key
# DB_ENCRYPTION_KEY_FILE=/path/to/database-encryption-key-file
DB_ENCRYPTION_KEY_ID=db-v1

# =============================================================================
# Organization Invitation Email Notifications (Resend)
# =============================================================================
# Enable email delivery for organization invitations
INVITATION_EMAIL_ENABLED=false

# Verified Resend sender address used as the From address when enabled.
# The sender domain must be verified in Resend before production delivery.
# INVITATION_EMAIL_FROM="NEAR AI Cloud <no-reply@near.ai>"

# Optional reply-to address
# INVITATION_EMAIL_REPLY_TO=support@example.com

# Resend API key. Prefer RESEND_API_KEY_FILE for deployed secrets.
# RESEND_API_KEY=re_xxxxxxxxx
# RESEND_API_KEY_FILE=/path/to/resend-api-key

# Public frontend base URL used for invitation email links
# CLOUD_UI_BASE_URL=https://cloud.near.ai

# Let NEAR wallet users add and verify a contact email (they sign in without
# one). Off by default. Independent of INVITATION_EMAIL_ENABLED, but when on it
# needs INVITATION_EMAIL_FROM, the Resend API key and CLOUD_UI_BASE_URL above:
# the emailed link opens {CLOUD_UI_BASE_URL}/verify-contact-email#token=...
CONTACT_EMAIL_VERIFICATION_ENABLED=false

# Most verification emails sent per 24 hours across all users (default 500).
# Requests over the cap get 429 until earlier sends leave the window.
# CONTACT_EMAIL_VERIFICATION_DAILY_CAP=500

# =============================================================================
# AML/KYT Checks for NEAR Wallet-Gated Flows (Lukka)
# =============================================================================
# Disabled by default. When enabling, LUKKA_AML_BEARER_TOKEN is required.
LUKKA_AML_ENABLED=false
# LUKKA_AML_BEARER_TOKEN=your-lukka-bearer-token
# LUKKA_AML_BASE_URL=https://api.blockchain-analytics.lukka.tech
# LUKKA_AML_REPORT_REFRESH_DAYS=30
# LUKKA_AML_MEMORY_CACHE_TTL_SECONDS=300
# LUKKA_AML_UNKNOWN_CACHE_TTL_SECONDS=60
# LUKKA_AML_REQUEST_TIMEOUT_SECONDS=10
# Supported risk levels are LOW, MEDIUM, and HIGH. UNKNOWN is never blocked by risk level alone.
# LUKKA_AML_BLOCKED_RISK_LEVELS=HIGH
# Use empty, none, or disabled to disable score-based blocking.
# When both risk levels and score threshold are configured, either matching predicate blocks.
# LUKKA_AML_SCORE_BLOCK_THRESHOLD=75
# LUKKA_AML_HIGH_RISK_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
# LUKKA_AML_HIGH_RISK_SLACK_TIMEOUT_MS=3000
# LUKKA_AML_HIGH_RISK_SLACK_DEDUPE_SECONDS=300

# =============================================================================
# Optional: Configuration Loading Mode
# =============================================================================
# Uncomment to explicitly use environment variables instead of config.yaml
# USE_ENV_CONFIG=true

# Or specify a custom config file path
# CONFIG_FILE=config/custom.yaml

# =============================================================================
# Integration Test Configuration (Optional)
# =============================================================================
# These variables are used by integration tests. If not set, tests will use
# default values suitable for local testing.

# vLLM Integration Tests
# VLLM_BASE_URL=http://localhost:8002
# VLLM_API_KEY=your_vllm_api_key_here
# VLLM_TEST_TIMEOUT_SECS=30

# =============================================================================
# Datadog Configuration (for Monitoring & Observability)
# =============================================================================
# Datadog API Key - Get this from https://app.datadoghq.com/account/settings#api
# REQUIRED for Datadog agent to send metrics/logs to Datadog
DD_API_KEY=your-datadog-api-key-here

# Datadog Site - Select your Datadog site region
# Options: datadoghq.com (US1), us3.datadoghq.com (US3), us5.datadoghq.com (US5), 
#          datadoghq.eu (EU1), ddog-gov.com (US1-FED)
DD_SITE=us3.datadoghq.com

# Environment tag for metrics (local, dev, staging, prod)
ENVIRONMENT=local

# =============================================================================
# OpenTelemetry Configuration
# =============================================================================
# OTLP endpoint for sending metrics (points to Datadog agent in docker-compose)
# TELEMETRY_OTLP_ENDPOINT=http://datadog-agent:4317
# TELEMETRY_OTLP_PROTOCOL=grpc
# Optional stable producer identity. In deployed CVMs, point this at the
# read-only staged VMM instance-id file; a configured file must be readable and
# contain a non-empty value after trimming.
# TELEMETRY_SERVICE_INSTANCE_ID_FILE=/run/cloud-api-identity/instance_id


BRAVE_SEARCH_PRO_API_KEY=MY_KEY
# Optional. Falls back to BRAVE_SEARCH_PRO_API_KEY when unset.
# BRAVE_LLM_CONTEXT_API_KEY=MY_KEY

# =============================================================================
# GitHub repository_dispatch on admin model PATCH
# =============================================================================
# When enabled, a successful PATCH /v1/admin/models fires a GitHub
# repository_dispatch event so downstream automation (model onboarding
# pipelines in cvm-ansible-playbooks) can react. Only enable on staging
# cloud-api; production keeps it off to avoid recursion when promote
# workflows PATCH prod.
# ENABLE_GITHUB_DISPATCH=false
# GITHUB_DISPATCH_REPO=nearai/cvm-ansible-playbooks
# GITHUB_DISPATCH_EVENT_TYPE=stg_model_loaded
# Provide PAT either inline or via file path (file pattern matches other secrets)
# GITHUB_DISPATCH_PAT=ghp_...
# GITHUB_DISPATCH_PAT_FILE=/run/secrets/github_dispatch_pat

# =============================================================================
# Executive "Stats" dashboard — infra burn metric
# =============================================================================
# Values are environment-specific and MUST be supplied via deployment
# secrets/env (never commit bearer tokens). When unset, the corresponding data
# in /v1/admin/platform/infra-summary is marked stale. Set in your deployment:
#   INFRA_MACHINES_URL            internal host-inventory endpoint URL
#   INFRA_COST_PER_HOST_USD_MONTH flat cost per GPU host per month (USD)
#   INFRA_PROMETHEUS_URL           Prometheus-compatible base URL
#   INFRA_PROMETHEUS_BEARER_TOKEN viewer bearer token (secret)
#   INFRA_PROMETHEUS_ENV           DCGM env label (prod or staging)
#   INFRA_COST_PER_GPU_HOUR_USD    planning cost per allocated GPU-hour (USD)

# =============================================================================
# Native Anthropic Messages API (hard-off by default)
# =============================================================================
# Exposes POST /v1/messages and POST /v1/messages/count_tokens for Anthropic-
# backed catalog models. Enable on staging first; leave unset/false in production
# until the native compatibility and billing gates have completed their soak.
# The upstream credential can be supplied inline or through a mounted file.
#   ENABLE_ANTHROPIC_MESSAGES=false            # "true"/"1" to enable
#   ANTHROPIC_DENIED_BETAS=                     # optional comma-separated tokens to refuse
#                                               # (unknown tokens are relayed to Anthropic)
#   ANTHROPIC_API_KEY=sk-ant-...                # secret
#   ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_api_key

# =============================================================================
# Chutes attested third-party inference provider (hard-off by default)
# =============================================================================
# When enabled, the configured Chutes models are served over a verified
# ML-KEM-768 E2EE channel: every request attests the chosen instance (TDX quote
# + report_data bindings + register-pinned measurement + GPU) before sending.
# Leave ENABLE_CHUTES unset/false to keep Chutes fully off (no behavior change).
#   ENABLE_CHUTES=false                       # "true"/"1" to enable
#   CHUTES_API_KEY=cpk_...                    # secret; or CHUTES_API_KEY_FILE=/path
#   CHUTES_MODELS=zai-org/GLM-5.1-FP8=zai-org/GLM-5.1-TEE,moonshotai/Kimi-K2.6-TEE
#       # Comma-separated `canonical_id=chute_slug` pairs. The CANONICAL id is what
#       # we expose in /v1/models and route under; the CHUTE SLUG (the `-TEE` form)
#       # is the internal upstream identity sent to Chutes. Use the NEAR-served id as
#       # the canonical when NEAR also serves the model (e.g. zai-org/GLM-5.1-FP8),
#       # else the OpenRouter id. A bare entry (no `=`) means canonical == slug.
#       # The slug side takes an optional `@<max_context_tokens>` suffix declaring
#       # the chute's context window (e.g. z-ai/glm-5.2=zai-org/GLM-5.2-TEE@1048576)
#       # so context-length routing knows whether Chutes can take a long request.
#       # Unset = no declared limit (never filtered by size).
#   CHUTES_ENABLE_STREAMING=false             # opt into streaming (default off; non-streaming is the
#                                             # honest attested default — streaming has no authenticated frame ordering)
#   PCCS_URL=...                              # optional Intel PCCS for DCAP collateral
#                                             # (single source of truth — shared with the NEAR verifier)
#
# ROUTING / FALLBACK: Chutes is registered as a fallback PROVIDER under each
# canonical id. If NEAR also serves that id, NEAR's own attested fleet is the
# primary and Chutes is the fallback (per-request, on a retryable NEAR failure);
# if NEAR does not serve it, Chutes is the only provider (primary). A *verifiable*
# model (one with any attested provider) NEVER falls back to a non-attested
# (plaintext) provider — it fails closed instead.
#
# CATALOG: each canonical id needs a row in the model catalog (DB) for
# /v1/chat/completions to route to it AND for usage to be billed (usage rows FK to
# models.id). On startup we AUTO-SEED a missing row as INACTIVE (is_active=false)
# with ZERO pricing. To go live you MUST `PATCH /v1/admin/models` with real
# per-token rates AND is_active=true (one call). The inactive seed makes it
# impossible to serve — and therefore bill at $0 — before pricing is set. An
# existing row (e.g. a NEAR-served canonical id) is respected verbatim (never
# clobbered); a disabled row stays disabled.

# =============================================================================
# Tinfoil attested third-party inference provider (ids reserved, no provider yet)
# =============================================================================
#   TINFOIL_API_KEY=...                       # secret; or TINFOIL_API_KEY_FILE=/path
#   TINFOIL_MODELS=zai-org/GLM-5.1-FP8=glm-5-1@202752
#       # Comma-separated `canonical_id=tinfoil_slug@max_ctx` entries. The CANONICAL
#       # id is what we expose and route under; the slug is Tinfoil's upstream model
#       # name. `@max_ctx` (max context tokens) is mandatory for Tinfoil entries.
#       # Any id listed here is RESERVED fail-closed (never served by a non-attested
#       # provider) even when TINFOIL_API_KEY is unset.

# =============================================================================
# Context-length tier routing (long-context models, e.g. GLM-5.2 262k/1M tiers)
# =============================================================================
# A NEAR-served model can run TWO capacity tiers behind one canonical id: the
# model row's provider_config declares the long tier —
#   {"long_context": {"inference_url": "https://glm-5-2-long.completions.near.ai",
#                     "max_context_tokens": 1048576,
#                     "base_max_context_tokens": 262144}}
# — and the pool registers a second provider under the same id. Requests whose
# estimated context requirement (input estimate + max_tokens reserve) does not
# fit the base fleet's window route to the long tier, then to the Chutes
# fallback. Models without the block are untouched. Catalog `contextLength`
# stays the customer-facing maximum (the long tier's window).
#
# Estimator knobs (defaults are fine; all optional):
#   CONTEXT_ROUTE_SAFETY_FACTOR=1.2        # multiplier on the bytes/4 heuristic
#   CONTEXT_ROUTE_EXACT_FACTOR=1.05        # multiplier on exact /v1/tokenize counts
#   CONTEXT_ROUTE_TOKENIZE_BAND_LOW=0.7    # exact-count band around a capacity:
#   CONTEXT_ROUTE_TOKENIZE_BAND_HIGH=1.3   #   low*cap <= input estimate + max_tokens reserve <= high*cap
#   CONTEXT_ROUTE_MEDIA_PART_TOKENS=1024   # flat tokens per non-text content part

# Comma-separated canonical model IDs enabled for native stateless /v1/responses.
# Empty/unset disables it. Exact matching: list snapshots explicitly. Aliases resolve to canonical IDs.
# Only store=false without state references/background is eligible; Chat Completions is unchanged.
# Example: NATIVE_RESPONSES_MODELS=openai/gpt-6-astra
NATIVE_RESPONSES_MODELS=

# TypeSafe Jev / System One. Register an external model with backend "typesafe"
# and outputModalities ["decisions"]; see docs/jev-systemone.md.
# Prefer TYPESAFE_API_KEY_FILE for a mounted secret; it takes precedence.
# TYPESAFE_API_KEY=
# TYPESAFE_API_KEY_FILE=/run/secrets/typesafe_api_key

# Opt into verified selected-organization wallet binding and automatic wallet Admin membership.
# Requires V0092 and the matching frontend; defaults false.
STAKING_FARM_SELECTED_ORG_BINDING_ENABLED=false