.env.example

# hypha environment overrides
# config.yaml defines typed structure and safe local defaults.
# .env should contain deployment-specific URLs, credentials, and local paths.

# Server
HYPHA_APP_NAME=hypha
HYPHA_APP_VERSION=1.0.0
NODE_ENV=development
HOST=0.0.0.0
PORT=3000
HYPHA_API_PREFIX=/api/v1

# User-owned configuration. The optional YAML file is merged over the tracked
# config.yaml template so framework updates do not overwrite product settings.
HYPHA_CONFIG_PATH=
HYPHA_AGENT_CONFIG_PATH=
HYPHA_TOOL_CONFIG_PATH=
HYPHA_WORKFLOW_PATH=
HYPHA_PROMPT_TEMPLATES_PATH=
HYPHA_PROMPT_REGISTRY_PATH=

# Auth and default owner
JWT_SECRET=change-me-local-access-secret
HYPHA_OWNER_EMAIL=owner@hypha.local
HYPHA_OWNER_USERNAME=owner
HYPHA_OWNER_PASSWORD=hypha_owner_2026
HYPHA_OWNER_DISPLAY_NAME=hypha Owner

# Storage deployment selector
HYPHA_STORAGE_DEPLOYMENT=local
HYPHA_STORAGE_PROFILE=local

# Document storage: MongoDB
# Leave MONGODB_URI empty for local host/port. Set it for Atlas or another
# managed/self-hosted MongoDB endpoint.
MONGODB_URI=
MONGODB_DEPLOYMENT=local
MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_DATABASE=hypha
MONGODB_USERNAME=
MONGODB_PASSWORD=
MONGODB_TLS=false
MONGODB_AUTH_SOURCE=
MONGODB_REPLICA_SET=
MONGODB_DIRECT_CONNECTION=

# Messaging/cache/stream storage: Redis
# Leave REDIS_URL empty for local host/port. Use rediss:// URLs for managed TLS
# providers. KV_URL and RENDER_REDIS_URL are also recognized as runtime fallbacks.
REDIS_URL=
REDIS_DEPLOYMENT=local
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
REDIS_KEY_PREFIX=hypha:
REDIS_TLS=false

# Canonical Memory runtime
# native-default uses MongoDB + Redis. External profiles use MongoDB for
# durable mappings/operation evidence and do not require Redis.
HYPHA_MEMORY_CONFIG_PATH=./configs/memory-profiles.yaml
HYPHA_MEMORY_MONGO_TRANSACTION_MODE=auto

# Self-hosted Mem0 OSS
HYPHA_MEM0_OSS_URL=http://127.0.0.1:8888
HYPHA_MEM0_OSS_API_KEY=

# Managed Mem0 Platform
HYPHA_MEM0_PLATFORM_TOKEN=

# Local Hindsight MemoryBank
HYPHA_HINDSIGHT_URL=http://127.0.0.1:8888
HYPHA_HINDSIGHT_BEARER_TOKEN=

# Managed Vertex AI Memory Bank
HYPHA_MEMORYBANK_PROJECT=
HYPHA_MEMORYBANK_LOCATION=
HYPHA_MEMORYBANK_ENGINE=
# environment reads the rotating access-token variable below. google-metadata
# obtains short-lived Workload Identity credentials on Cloud Run/GKE/GCE.
HYPHA_MEMORYBANK_AUTH_MODE=environment
HYPHA_MEMORYBANK_ACCESS_TOKEN=

# Messaging/queue storage: Kafka
KAFKA_ENABLED=false
KAFKA_DEPLOYMENT=local
KAFKA_BROKERS=localhost:9092
KAFKA_CLIENT_ID=hypha
KAFKA_SSL=false
KAFKA_SASL_USERNAME=
KAFKA_SASL_PASSWORD=

# Relational storage: local SQLite
# Modes: auto, sqlite, json. node-sqlite is accepted as a compatibility alias.
HYPHA_SQLITE_MODE=auto
HYPHA_STORAGE_EVENT_DB=./data/runtime/events/hypha-runtime-events.sqlite
HYPHA_STORAGE_STRUCTURED_DB=./data/runtime/structured/hypha-structured.sqlite

# Relational storage: Postgres
POSTGRES_ENABLED=false
POSTGRES_DEPLOYMENT=local
POSTGRES_URL=
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=hypha
POSTGRES_USERNAME=
POSTGRES_PASSWORD=
POSTGRES_TLS=false

# Vector storage: local JSON index
HYPHA_STORAGE_VECTOR_INDEX=./data/storage/vector/hypha-vectors.json

# Vector storage: external providers
QDRANT_ENABLED=false
QDRANT_DEPLOYMENT=self_hosted
QDRANT_URL=
QDRANT_COLLECTION=hypha_memory
QDRANT_API_KEY=
QDRANT_TLS=false
CHROMA_ENABLED=false
CHROMA_DEPLOYMENT=local
CHROMA_URL=
CHROMA_COLLECTION=hypha_memory
CHROMA_TLS=false
PINECONE_ENABLED=false
PINECONE_DEPLOYMENT=managed
PINECONE_URL=
PINECONE_INDEX=hypha-memory
PINECONE_API_KEY=
PINECONE_REGION=
PINECONE_TLS=true

# Artifact storage
HYPHA_STORAGE_ARTIFACT_ROOT=./data/storage/artifacts
S3_ARTIFACTS_ENABLED=false
S3_ARTIFACTS_DEPLOYMENT=managed
S3_ARTIFACTS_BUCKET=
S3_ARTIFACTS_REGION=
S3_ARTIFACTS_ENDPOINT=

# System logs
HYPHA_SYSTEM_LOG_PATH=./data/logs/system.log

# Agent inference runtime
HYPHA_INFERENCE_RUNTIME_PROVIDER=model-provider
HYPHA_INFERENCE_DEFAULT_BACKEND=sglang
HYPHA_INFERENCE_ALLOW_CROSS_SESSION_CACHE=false
HYPHA_INFERENCE_ALLOW_CROSS_AGENT_CACHE=false
HYPHA_INFERENCE_MIN_PREFIX_TOKENS=1
HYPHA_INFERENCE_MAX_PREFIX_REFS=32

# Local inference engine lifecycle. connect uses an already-running engine;
# managed starts the configured command without a shell and waits for health.
HYPHA_LOCAL_INFERENCE_ENABLED=false
HYPHA_LOCAL_INFERENCE_ENGINE=ollama
HYPHA_LOCAL_INFERENCE_MODE=connect
HYPHA_LOCAL_INFERENCE_AUTO_START=false
HYPHA_LOCAL_INFERENCE_MODEL=
HYPHA_LOCAL_INFERENCE_HOST=127.0.0.1
HYPHA_LOCAL_INFERENCE_PORT=
HYPHA_LOCAL_INFERENCE_COMMAND=
HYPHA_LOCAL_INFERENCE_ARGS=
HYPHA_LOCAL_INFERENCE_CWD=
HYPHA_LOCAL_INFERENCE_STARTUP_TIMEOUT_MS=120000
HYPHA_LOCAL_INFERENCE_HEALTH_POLL_MS=500

# Inference backends
OLLAMA_INFERENCE_ENABLED=true
OLLAMA_INFERENCE_BASE_URL=http://localhost:11434
OLLAMA_INFERENCE_ENDPOINT=/api/chat
OLLAMA_INFERENCE_TIMEOUT_MS=60000
SGLANG_ENABLED=true
SGLANG_BASE_URL=http://localhost:30000
SGLANG_ENDPOINT=/generate
SGLANG_TIMEOUT_MS=60000
VLLM_ENABLED=true
VLLM_BASE_URL=http://localhost:8000
VLLM_ENDPOINT=/v1/chat/completions
VLLM_TIMEOUT_MS=60000
LLAMA_CPP_ENABLED=true
LLAMA_CPP_BASE_URL=http://localhost:8080
LLAMA_CPP_ENDPOINT=/completion
LLAMA_CPP_TIMEOUT_MS=60000
OPENAI_INFERENCE_ENABLED=true
OPENAI_INFERENCE_BASE_URL=https://api.openai.com/v1
OPENAI_INFERENCE_ENDPOINT=/chat/completions
OPENAI_INFERENCE_TIMEOUT_MS=60000

# Serving cache for LLM provider calls
# off keeps existing provider behavior unchanged. memory/sqlite enable exact
# request-response caching at the Hypha provider middleware layer.
HYPHA_SERVING_CACHE=off
HYPHA_SERVING_CACHE_MODE=readwrite
HYPHA_SERVING_CACHE_TTL_MS=86400000
HYPHA_SERVING_CACHE_RESPECT_NO_CACHE=true
HYPHA_SERVING_CACHE_SQLITE_PATH=./data/runtime/cache/hypha-serving-cache.sqlite
HYPHA_SERVING_CACHE_FAILURE_MODE=bypass
HYPHA_SERVING_CACHE_SCOPE_REQUIREMENT=user
HYPHA_SERVING_CACHE_OPERATION_TIMEOUT_MS=250
HYPHA_SERVING_CACHE_SINGLEFLIGHT=true
HYPHA_SERVING_CACHE_MAX_ENTRY_BYTES=1048576
HYPHA_SERVING_CACHE_REDIS_PREFIX=serving-cache:v1:

# WorkCache for event-derived typed runtime cache blocks
# cache-base defaults to memory so tree and WorkGraph updates are collected.
HYPHA_WORKCACHE=memory
HYPHA_WORKCACHE_SQLITE_PATH=./data/runtime/cache/hypha-workcache.sqlite
HYPHA_WORKCACHE_FAILURE_MODE=bypass
HYPHA_WORKCACHE_SCOPE_REQUIREMENT=user
HYPHA_WORKCACHE_OPERATION_TIMEOUT_MS=500
HYPHA_WORKCACHE_MAX_BLOCK_BYTES=2097152
HYPHA_WORKCACHE_REDIS_PREFIX=workcache:v1:
HYPHA_WORKCACHE_REDIS_INVALIDATION_CHANNEL=workcache:v1:invalidate
HYPHA_WORKCACHE_PROMPT_BUDGET_TOKENS=4096
HYPHA_WORKCACHE_UNKNOWN_EVENT_POLICY=ignore
HYPHA_WORKCACHE_ALLOW_EXTENSION_EVENTS=false
HYPHA_WORKCACHE_PLAN_TTL_MS=86400000
HYPHA_WORKCACHE_COMPUTATION_TTL_MS=21600000
HYPHA_WORKCACHE_TOOL_TTL_MS=3600000
HYPHA_WORKCACHE_OBSERVATION_TTL_MS=3600000
HYPHA_WORKCACHE_VERIFICATION_TTL_MS=3600000
HYPHA_WORKCACHE_MEMORY_TTL_MS=86400000
HYPHA_WORKCACHE_RECOVERY_TTL_MS=21600000
HYPHA_WORKCACHE_PROMPT_PREFIX_TTL_MS=86400000

# Governed Tool result cache. Read Tools also require an explicit external state version.
# `redis` uses the Redis connection above and works with local, self-hosted, or managed Redis.
HYPHA_TOOL_RESULT_CACHE=off
HYPHA_TOOL_RESULT_CACHE_FAILURE_MODE=bypass
HYPHA_TOOL_RESULT_CACHE_TIMEOUT_MS=250
HYPHA_TOOL_RESULT_CACHE_MAX_ENTRIES=1000
HYPHA_TOOL_RESULT_CACHE_MAX_ENTRY_BYTES=1048576
HYPHA_TOOL_RESULT_CACHE_REDIS_DEFAULT_TTL_MS=86400000
HYPHA_TOOL_RESULT_CACHE_NAMESPACE=tool-result-cache:v1

# LLM defaults
HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
HYPHA_LLM_DEFAULT_CHAT_TARGET=openai:gpt-4o-mini
HYPHA_LLM_DEFAULT_FAST_TARGET=openai:gpt-4o-mini
HYPHA_LLM_DEFAULT_REASONING_TARGET=openai:gpt-4o-mini

# LLM provider credentials
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
ANTHROPIC_API_KEY=
ANTHROPIC_BASE_URL=https://api.anthropic.com
GOOGLE_API_KEY=
GOOGLE_BASE_URL=https://generativelanguage.googleapis.com
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
OLLAMA_BASE_URL=http://localhost:11434

# Optional OpenAI-compatible providers
KIMI_API_KEY=
SILICONFLOW_API_KEY=
GROQ_API_KEY=
TOGETHER_API_KEY=
PERPLEXITY_API_KEY=

# Runtime extension paths
HYPHA_SKILLS_DIR=

# Governed local filesystem tool
# Comma-separate multiple roots. Configured roots resolve from the server
# process directory; tool request paths resolve from the dedicated workspace.
HYPHA_FILESYSTEM_WORKING_DIRECTORY=./data/workspace
HYPHA_FILESYSTEM_READ_PATHS=./data/workspace
HYPHA_FILESYSTEM_WRITE_PATHS=./data/workspace
HYPHA_FILESYSTEM_EXECUTE_PATHS=./data/workspace/bin
HYPHA_FILESYSTEM_EXECUTION_ENABLED=false
HYPHA_FILESYSTEM_EXECUTION_TIMEOUT_MS=30000
HYPHA_FILESYSTEM_MAX_OUTPUT_BYTES=1048576
# Legacy single-root compatibility. Prefer the scoped variables above.
FILESYSTEM_TOOL_ROOT=

# Web search tool
# Production defaults must resolve to real HTTP providers. The deterministic
# "stub" provider is available only for explicit test and non-production use.
WEB_SEARCH_PROVIDER=auto
WEB_SEARCH_PROVIDER_ORDER=duckduckgo,wikipedia
WEB_SEARCH_CHINA_PROVIDER_ORDER=baidu,so360
WEB_SEARCH_FALLBACK_PROVIDERS=wikipedia
WEB_SEARCH_ENDPOINT=
WEB_SEARCH_DUCKDUCKGO_ENDPOINT=https://api.duckduckgo.com/
WEB_SEARCH_WIKIPEDIA_ENDPOINT=https://en.wikipedia.org/w/api.php
WEB_SEARCH_BAIDU_SUGGEST_ENDPOINT=https://www.baidu.com/sugrec
WEB_SEARCH_SO360_SUGGEST_ENDPOINT=https://sug.so.360.cn/suggest
WEB_SEARCH_TIMEOUT_MS=10000
WEB_SEARCH_USER_AGENT=hypha/1.0 web-search

# CLI client overrides
HYPHA_HOME=
HYPHA_BASE_URL=http://127.0.0.1:3000/api/v1
HYPHA_PROVIDER=
HYPHA_MODEL=

# Optional live acceptance for externally provisioned providers.
# These values are user-supplied and are not required for the base npm release.
HYPHA_ACCEPTANCE_COMMIT_SHA=
HYPHA_TEST_MONGODB_URI=
HYPHA_TEST_MEM0_OSS_URL=
HYPHA_TEST_MEM0_OSS_API_KEY=
HYPHA_TEST_MEM0_OSS_VERSION=
HYPHA_TEST_MEM0_PLATFORM_URL=
HYPHA_TEST_MEM0_PLATFORM_TOKEN=
HYPHA_TEST_MEM0_PLATFORM_VERSION=
HYPHA_TEST_HINDSIGHT_URL=
HYPHA_TEST_HINDSIGHT_TOKEN=
HYPHA_TEST_HINDSIGHT_VERSION=
HYPHA_TEST_HINDSIGHT_DOCKER_CONTAINER=
HYPHA_TEST_HINDSIGHT_IMAGE=
HYPHA_TEST_MEMORYBANK_MANAGED_TOKEN=
HYPHA_TEST_MEMORYBANK_PROJECT=
HYPHA_TEST_MEMORYBANK_LOCATION=
HYPHA_TEST_MEMORYBANK_ENGINE=
HYPHA_TEST_MEMORYBANK_MANAGED_VERSION=
HYPHA_REAL_REMOTE_SANDBOX_BASE_URL=
HYPHA_REAL_REMOTE_SANDBOX_ACCESS_TOKEN=
HYPHA_REAL_REMOTE_SANDBOX_PROVIDER_ID=
HYPHA_REAL_REMOTE_SANDBOX_COMMANDS_JSON=

# MCP runtime adapters
# config.yaml enables a real local stdio MCP child process by default. For remote MCP,
# reference MCP_GATEWAY_URL and MCP_GATEWAY_TOKEN from a tools.mcpServers entry.
MCP_GATEWAY_URL=http://localhost:3001
MCP_GATEWAY_TOKEN=

# Development-only helper accounts
DEV_ADMIN_EMAIL=admin@hypha.local
DEV_ADMIN_PASSWORD=hypha_admin_2026
DEV_TEST_EMAIL=dev@test.local
DEV_TEST_PASSWORD=devpassword123