Environment Overrides
Backend
soha no longer uses .env.example as its primary configuration source.
Backend configuration lives in configs/config.yaml. Environment variables are only used for overrides when deployment environments need to change file defaults.
Typical overrides:
SOHA_CONFIG_FILESOHA_HTTP_ADDRSOHA_LOGGER_LEVELSOHA_LOGGER_FORMAT(defaults tojsonin production; useconsolefor local debugging)SOHA_DATABASE_HOSTSOHA_DATABASE_PORTSOHA_DATABASE_NAMESOHA_DATABASE_USERSOHA_DATABASE_PASSWORDSOHA_AUTH_DEV_PRINCIPAL_PASSWORDSOHA_AUTH_JWT_SECRETSOHA_RUNTIME_EXECUTION_RUNNER_TOKENSOHA_MONITORING_WEBHOOK_TOKENSOHA_SECURITY_CREDENTIAL_ENCRYPTION_KEYSOHA_SECURITY_SECRET_PROVIDERSOHA_SECURITY_VAULT_KV2_ADDRESSSOHA_SECURITY_VAULT_KV2_TOKENSOHA_SECURITY_VAULT_KV2_NAMESPACESOHA_SECURITY_VAULT_KV2_TIMEOUTSOHA_SECURITY_VAULT_KV2_MAX_RESPONSE_BYTESSOHA_REDIS_ADDRSOHA_AUTH_ENABLE_DEV_AUTH
The repository config and all deployment forms default the database password to pgsql and the initial opensoha administrator password to opensoha. Soha does not vary or reject these standard initial credentials based on an application environment label; both remain explicitly overridable.
The JWT signing secret, execution runner token, monitoring webhook token, and credential encryption key all default to soha-123456789012345678901234567890. Soha accepts that documented value and does not require a SecretStore file, writer lease, or secret PVC at startup. Public or formal deployments should override all four variables independently. Changing SOHA_SECURITY_CREDENTIAL_ENCRYPTION_KEY requires migrating existing ciphertext first; otherwise previously stored credentials cannot be decrypted.
Set SOHA_SECURITY_SECRET_PROVIDER=vault_kv2 to enable Vault-backed Secret versions. SOHA_SECURITY_VAULT_KV2_TOKEN is a server credential: inject it through the deployment secret mechanism and do not expose it to CLI, Web, MCP, skills, or OpenAPI callers. Vault-backed versions pin a KV v2 version; an unavailable provider fails closed.
Runner and Gateway examples also use these operational variables:
SOHA_EXECUTION_RUNNER_TOKEN: shell/example helper used to pass the bearer token to runner or Helm commands; the backend Viper override isSOHA_RUNTIME_EXECUTION_RUNNER_TOKEN.HERMES_CONTROL_PLANE_URL: optional override for the Hermes runner control-plane URL in local compose examples.SOHA_AI_GATEWAY_RATE_LIMIT_BACKEND: optional AI Gateway rate-limit backend, for exampleredis.SOHA_AI_GATEWAY_RATE_LIMIT_REDIS_ADDR: Redis address used by the AI Gateway rate limiter when Redis is selected.
CLI and tutorial examples use these client-side variables:
SOHA_CONFIG: alternate local CLI profile file path.SOHA_TOKEN: bearer token used by direct curl examples.SOHA_SERVER: base URL used by direct curl examples.SOHA_SKILLS_SOURCE: alternate source directory for local skill installation.SOHA_SKILLS_DIR: alternate local skill installation directory.
Frontend
VITE_API_BASE_URLoverrides the API base; its default is same-origin/api/v1- the candidate
VITE_BASE_PATH=/team/build prefixes assets, Router paths and the default API base; export it when building or starting Vite VITE_API_PROXY_TARGETselects the development upstream, defaulthttp://127.0.0.1:8080, in../soha/web/vite.config.ts- the in-app docs page opens
/docs/; thesohaserver redirects that path to the configured external docs URL by default
For a prefixed production deployment, configure request and cookie-path rewrites as described in deployment. Build-time Web variables are public and must never contain credentials. Prefer a same-origin reverse proxy so browser session cookies and authorization checks use the intended instance.
Docs
soha-docs has its own build-time configuration.
DOCS_SITE_URL: published site origin, defaulthttps://docs.opensoha.devDOCS_BASE_URL: published path prefix, default/DOCS_SHOW_LAST_UPDATE_TIME: retained for docs workflow compatibility; Nextra does not currently render it
For https://docs.opensoha.dev/, build with DOCS_BASE_URL=/. For https://opensoha.dev/docs/, build with DOCS_BASE_URL=/docs/.
CLI authentication isolation (pending release combination)
SOHA_AUTH_CLI_ENABLED,SOHA_AUTH_CLI_PUBLIC_URLandSOHA_AUTH_CLI_ALLOW_PASSWORDcontrol new Core session endpoints, disabled by default; see configuration. Other CLI TTL/budget fields use the correspondingSOHA_AUTH_CLI_*mapping.- CLI
SOHA_CONFIGselects a private configuration path. Use separate paths for worktrees, instances and CI jobs. - Providing CLI
SOHA_SERVERandSOHA_TOKENtogether enables stateless environment authentication without reading or refreshing a profile. The token is never persisted. - Overriding only
SOHA_SERVERcannot send stored credentials to another origin or deployment path; mismatches returnserver_mismatchbefore network access. SOHA_TOKENoverrides local authentication and is not unset by logout. Remove it from the shell/job environment.