Clavis SSOT
vox-clavis is the canonical source of truth for managed secret metadata and resolution precedence.
Research and forward-looking analysis live in Clavis secrets, env vars, and API key strategy research 2026. Threat and policy controls are documented in Clavis Cloudless Threat Model V1, with execution steps in Clavis Cloudless Implementation Catalog.
Naming Convention
VOX_*: Vox-owned platform contracts (mesh, runtime auth, DB, cloud orchestration, internal boundaries).
Non-secret environment parsing
Use vox_config::env_parse for numeric defaults and operator tuning (e.g. HTTP retry caps, timeouts expressed as plain integers). Do not route API keys or other credentials through those helpers — use vox_clavis::resolve_secret (and the SecretId inventory below) so precedence and aliases stay consistent.
vox-ludus free-tier AI: when FreeAiProvider::{Gemini,OpenRouter} carries an empty api_key, resolution goes through Clavis (GeminiApiKey, OpenRouterApiKey) — same canonical + compat env names as the rest of the repo; do not read GEMINI_API_KEY / OPENROUTER_API_KEY directly in new Ludus codepaths.
- Provider-native names (for example
OPENROUTER_API_KEY,OPENAI_API_KEY): upstream ecosystem names kept for compatibility. - Optional
VOX_*provider aliases are accepted as migration aids; canonical names remain stable.
Secret Inventory (Phase 0)
| Secret | Scope | Tier | Primary consumer surfaces |
|---|---|---|---|
OPENROUTER_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY | LLM inference | Minimal cloud LLM | vox-mcp, vox-runtime, vox-cli doctor/status |
HF_TOKEN | LLM retrieval / HF router | Optional | vox-config, HF routes |
GROQ_API_KEY, CEREBRAS_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY, SAMBANOVA_API_KEY, CUSTOM_OPENAI_API_KEY | Alternative LLM providers | Optional power-user | provider-specific runtime/mcp paths |
VOX_RUNPOD_API_KEY, VOX_VAST_API_KEY | Cloud GPU infra | Optional cloud GPU | vox-populi cloud providers |
TOGETHER_API_KEY | Remote fine-tune API | Optional cloud training | vox-cli train --provider together |
GITHUB_TOKEN | Publishing/review automation | Workflow-specific required | vox-cli review/publish |
VOX_NEWS_TWITTER_TOKEN, VOX_NEWS_OPENCOLLECTIVE_TOKEN, VOX_SOCIAL_REDDIT_*, VOX_SOCIAL_YOUTUBE_* | Scientia/news syndication | Optional (per channel) | vox-publisher resolves via Clavis SecretId specs; GitHub syndication also accepts VOX_NEWS_GITHUB_TOKEN as an alias of GITHUB_TOKEN |
ZENODO_ACCESS_TOKEN, OPENREVIEW_EMAIL, OPENREVIEW_ACCESS_TOKEN, OPENREVIEW_PASSWORD, CROSSREF_PLUS_API_KEY, DATACITE_REPOSITORY, DATACITE_PASSWORD, ORCID_CLIENT_ID, ORCID_CLIENT_SECRET, TAVILY_API_KEY, TAVILY_PROJECT, X_TAVILY_API_KEY, VOX_ARXIV_ASSIST_HANDOFF_SECRET (plus VOX_* aliases for DataCite, ORCID, Tavily where listed below) | Scholarly repository adapters | Optional (Workflow::Publish / publish_review bundle) | Zenodo / OpenReview / Crossref / DataCite / ORCID / Tavily clients resolve via Clavis; VOX-prefixed aliases accepted where listed |
VOX_DB_URL, VOX_DB_TOKEN | Remote DB | Workflow-specific required | DB remote flows |
VOX_TELEMETRY_UPLOAD_URL, VOX_TELEMETRY_UPLOAD_TOKEN | Optional telemetry ingest (explicit vox telemetry upload) | Optional | vox-cli resolves via SecretId::VoxTelemetryUploadUrl / VoxTelemetryUploadToken; see ADR 023 |
VOX_SEARCH_QDRANT_API_KEY | Qdrant HTTP api-key (optional RAG sidecar) | Optional | vox_search::vector_qdrant via SecretId::VoxSearchQdrantApiKey |
VOX_MESH_TOKEN | Populi control-plane auth (legacy full-access token) | Workflow-specific required (any mesh-class token) | Mesh transport/auth |
VOX_MESH_WORKER_TOKEN | Worker-scoped populi HTTP bearer | Optional (advance pools) | POST join/heartbeat/inbox/ack |
VOX_MESH_SUBMITTER_TOKEN | Submitter-scoped populi HTTP bearer | Optional | POST A2A deliver only |
VOX_MESH_ADMIN_TOKEN | Mesh admin bearer | Optional | Full HTTP surface when configured |
VOX_MESH_JWT_HMAC_SECRET | HS256 key for mesh JWT bearer | Optional | JWT claims role, jti, exp |
VOX_MESH_WORKER_RESULT_VERIFY_KEY | Ed25519 verify key (hex or Standard base64) | Optional | Signed job_result / job_fail payloads |
VOX_API_KEY, VOX_BEARER_TOKEN | Runtime ingress auth | Optional hardening | vox-runtime auth gate |
VOX_MCP_HTTP_BEARER_TOKEN, VOX_MCP_HTTP_READ_BEARER_TOKEN | MCP HTTP gateway auth | Optional hardening | vox-mcp HTTP gateway auth surfaces |
V0_API_KEY, VOX_OPENCLAW_TOKEN | Auxiliary tooling | Optional | island generation / OpenClaw |
Managed Secret Env Names
ANTHROPIC_API_KEYAPI_KEYCEREBRAS_API_KEYCODERABBIT_GITHUB_PER_PAGECUSTOM_OPENAI_API_KEYDEEPSEEK_API_KEYFORGE_TOKENGEMINI_API_KEYGH_TOKEN(DEPRECATED — use FORGE_TOKEN)GITHUB_SHAGITHUB_TOKENGITLAB_TOKENGL_TOKEN(DEPRECATED — use FORGE_TOKEN)GOOGLE_AI_STUDIO_KEY(DEPRECATED — use GEMINI_API_KEY)GROQ_API_KEYHF_TOKENHUGGING_FACE_HUB_TOKEN(DEPRECATED — use HF_TOKEN)MISTRAL_API_KEYOLLAMA_HOSTOLLAMA_MODELOLLAMA_URLOPENAI_API_KEYOPENCLAW_TOKENOPENROUTER_API_KEYOPENROUTER_APP_TITLEOPENROUTER_HTTP_REFEREROPENROUTER_MODELOPENROUTER_ROUTE_HINTRUNPOD_API_KEYSAMBANOVA_API_KEYSKIP_CUDA_FEATURE_CHECKTAVILY_API_KEYTAVILY_PROJECTTAVILY_PROJECT_IDTOGETHER_API_KEYTURSO_AUTH_TOKEN(DEPRECATED — use VOX_DB_TOKEN)TURSO_URL(DEPRECATED — use VOX_DB_URL)V0_API_KEYVAST_API_KEYVOX_ALLOW_QWEN2_NATIVEVOX_ANTHROPIC_API_KEYVOX_ANTHROPIC_CHAT_COMPLETIONS_URLVOX_ANTHROPIC_DIRECTVOX_API_KEYVOX_ARXIV_ASSIST_HANDOFF_SECRETVOX_BASE_MODELVOX_BEARER_TOKENVOX_BUDGET_USDVOX_CANDLE_DEVICEVOX_CARGO_BINVOX_CEREBRAS_API_KEYVOX_CEREBRAS_CHAT_COMPLETIONS_URLVOX_CLI_GLOBAL_JSONVOX_CLI_JSONVOX_CLOUD_IMAGEVOX_CLOUD_MAX_RUNTIMEVOX_CLOUD_PRICE_TTLVOX_COST_PREFERENCEVOX_CROSSREF_PLUS_API_KEYVOX_DATACITE_PASSWORDVOX_DATACITE_REPOSITORYVOX_DATA_DIRVOX_DB_TOKENVOX_DB_URLVOX_DEEPSEEK_API_KEYVOX_DEEPSEEK_CHAT_COMPLETIONS_URLVOX_DOGFOOD_TRACE_PATHVOX_EMIT_EXPRESS_SERVERVOX_FORGE_TOKENVOX_GAMIFY_ENABLEDVOX_GAMIFY_MODEVOX_GEMINI_API_KEYVOX_GPU_MODELVOX_GPU_VRAM_MBVOX_GROQ_API_KEYVOX_GROQ_CHAT_COMPLETIONS_URLVOX_HF_TOKENVOX_JSON_OUTPUTVOX_MCP_BINARYVOX_MCP_HTTP_BEARER_TOKENVOX_MCP_HTTP_READ_BEARER_TOKENVOX_MENS_EXPERIMENTAL_OPTIMIZERVOX_MENS_SCORECARD_MAX_TOKENSVOX_MENS_TRAIN_JSONL_STRICTVOX_MENS_TRAIN_JSON_STRICTVOX_MESH_ADMIN_TOKENVOX_MESH_HTTP_HEARTBEAT_SECSVOX_MESH_HTTP_JOINVOX_MESH_JWT_HMAC_SECRETVOX_MESH_SUBMITTER_TOKENVOX_MESH_TOKENVOX_MESH_WORKER_RESULT_VERIFY_KEYVOX_MESH_WORKER_TOKENVOX_MISTRAL_API_KEYVOX_MISTRAL_CHAT_COMPLETIONS_URLVOX_MODELVOX_NEWS_OPENCOLLECTIVE_TOKENVOX_OPENAI_API_KEYVOX_OPENCLAW_SIDECAR_DISABLEVOX_OPENCLAW_SIDECAR_EXPECT_VERSIONVOX_OPENCLAW_TOKENVOX_OPENCLAW_URLVOX_OPENCLAW_WS_URLVOX_OPENREVIEW_ACCESS_TOKENVOX_OPENREVIEW_API_BASEVOX_OPENREVIEW_EMAILVOX_OPENREVIEW_INVITATIONVOX_OPENREVIEW_PASSWORDVOX_OPENREVIEW_SIGNATUREVOX_OPENROUTER_API_KEYVOX_ORCHESTRATOR_ATTENTION_BUDGET_MSVOX_ORCHESTRATOR_ATTENTION_ENABLEDVOX_ORCHESTRATOR_ENABLEDVOX_ORCHESTRATOR_LOG_LEVELVOX_ORCHESTRATOR_PLANNING_ENABLEDVOX_ORCHESTRATOR_RESEARCH_MODEL_ENABLEDVOX_ORCID_CLIENT_IDVOX_ORCID_CLIENT_SECRETVOX_PM_ALLOW_GIT_UNVERIFIEDVOX_PROVIDER_DAILY_LIMITS_FILEVOX_PROVIDER_DAILY_LIMITS_JSONVOX_PROVIDER_DAILY_LIMIT_DEFAULTVOX_PROVIDER_LIMIT_PROVIDERSVOX_QWEN35_NATIVE_CUTOVERVOX_REGISTRY_TOKENVOX_REPOSITORY_ROOTVOX_REPO_ROOTVOX_REVIEW_REPOSITORY_IDVOX_SAMBANOVA_API_KEYVOX_SAMBANOVA_CHAT_COMPLETIONS_URLVOX_SCHOLARLY_ADAPTERVOX_SCHOLARLY_DISABLEVOX_SCHOLARLY_DISABLE_LIVEVOX_SCHOLARLY_DISABLE_OPENREVIEWVOX_SCHOLARLY_DISABLE_ZENODOVOX_SCRIPT_CACHE_MAX_ENTRIESVOX_SCRIPT_CACHE_MAX_SIZE_MBVOX_SCRIPT_RELEASEVOX_SEARCH_QDRANT_API_KEYVOX_SECRET_GUARD_GIT_REFVOX_SOCIAL_BLUESKY_HANDLEVOX_SOCIAL_BLUESKY_PASSWORDVOX_SOCIAL_DISCORD_WEBHOOKVOX_SOCIAL_LINKEDIN_ACCESS_TOKENVOX_SOCIAL_MASTODON_DOMAINVOX_SOCIAL_MASTODON_TOKENVOX_SOCIAL_REDDIT_CLIENT_IDVOX_SOCIAL_REDDIT_CLIENT_SECRETVOX_SOCIAL_REDDIT_REFRESH_TOKENVOX_SOCIAL_REDDIT_USER_AGENTVOX_SOCIAL_YOUTUBE_CLIENT_IDVOX_SOCIAL_YOUTUBE_CLIENT_SECRETVOX_SOCIAL_YOUTUBE_REFRESH_TOKENVOX_SYNDICATION_TEMPLATE_PROFILEVOX_TAVILY_API_KEYVOX_TAVILY_PROJECTVOX_TAVILY_PROJECT_IDVOX_TELEMETRY_UPLOAD_TOKENVOX_TELEMETRY_UPLOAD_URLVOX_TOGETHER_API_KEYVOX_TRAIN_PROFILEVOX_TURSO_TOKEN(DEPRECATED — use VOX_DB_TOKEN)VOX_TURSO_URL(DEPRECATED — use VOX_DB_URL)VOX_V0_API_KEYVOX_VRAM_OVERRIDE_GBVOX_WEBHOOK_INGRESS_TOKENVOX_WEBHOOK_SIGNING_SECRETVOX_WEB_RUN_MODEVOX_WEB_TANSTACK_STARTVOX_WORKSPACE_ROOTVOX_ZENODO_ACCESS_TOKENVOX_ZENODO_API_BASEVOX_ZENODO_ATTACH_MANIFEST_BODYVOX_ZENODO_DRAFT_ONLYVOX_ZENODO_PUBLISH_DEPOSITIONVOX_ZENODO_PUBLISH_NOWVOX_ZENODO_SANDBOXVOX_ZENODO_STAGING_DIRVOX_ZENODO_UPLOAD_ALLOWLISTX_TAVILY_API_KEY(DEPRECATED — use TAVILY_API_KEY)ZENODO_ACCESS_TOKEN
Operator Tuning Variables (Non-Secrets)
CARGO_HOMECOMPUTERNAMEGEMINI_MODELHF_CHAT_MODELHF_DEDICATED_CHAT_MODELHF_DEDICATED_CHAT_URLHOMEHOSTNAMEINFISICAL_SERVICE_TOKENINFISICAL_TOKENOLLAMA_MODELOLLAMA_URLOPENAI_BASE_URLOPENAI_MODELOPENROUTER_CHAT_MODELOPENROUTER_MODELPOPULI_MAX_TOKENSPOPULI_MODELPOPULI_TEMPERATUREPOPULI_URLRUST_LOGUSERPROFILEVAULT_ADDRVAULT_TOKENVOX_ACCOUNT_IDVOX_ALLOW_UNAUTHENTICATEDVOX_BASE_MODELVOX_BENCHMARK_TELEMETRYVOX_BUDGET_USDVOX_CHROME_EXECUTABLEVOX_CLAVIS_AUTO_PREFER_VAULTVOX_CLAVIS_AUTO_VAULTVOX_CLAVIS_BACKENDVOX_CLAVIS_CLOUDLESS_DB_PATHVOX_CLAVIS_CUTOVER_PHASEVOX_CLAVIS_HARD_CUTVOX_CLAVIS_KEK_REFVOX_CLAVIS_KEK_VERSIONVOX_CLAVIS_MIGRATION_PHASEVOX_CLAVIS_PROFILEVOX_CLAVIS_VAULT_PATHVOX_CLAVIS_VAULT_TOKENVOX_CLAVIS_VAULT_URLVOX_DATA_DIRVOX_DB_CIRCUIT_BREAKERVOX_DB_EMBEDDED_REPLICA_INTEGRATIONVOX_DB_MVCCVOX_DB_SYNC_INTEGRATIONVOX_DB_TOKENVOX_DB_URLVOX_EMBEDDING_MODELVOX_EXEVOX_GAMIFY_ENABLEDVOX_GAMIFY_MODEVOX_GPU_MODELVOX_GPU_VRAM_MBVOX_INFERENCE_PROFILEVOX_MCP_BINARYVOX_MENS_TRAIN_JSONL_STRICTVOX_MESH_A2A_LEASE_MSVOX_MESH_A2A_MAX_MESSAGESVOX_MESH_A2A_STORE_PATHVOX_MESH_ADVERTISE_GPUVOX_MESH_BOOTSTRAP_EXPIRES_UNIX_MSVOX_MESH_BOOTSTRAP_TOKENVOX_MESH_CODEX_TELEMETRYVOX_MESH_CONTROL_ADDRVOX_MESH_DEVICE_CLASSVOX_MESH_DISPATCH_STORE_PATHVOX_MESH_ENABLEDVOX_MESH_EXEC_LEASE_STORE_PATHVOX_MESH_EXEC_POLICYVOX_MESH_HTTP_MAX_BODY_BYTESVOX_MESH_LABELSVOX_MESH_MAX_STALE_MSVOX_MESH_MODEVOX_MESH_NODE_IDVOX_MESH_RANKVOX_MESH_REGISTRY_PATHVOX_MESH_REPLAY_PERSISTVOX_MESH_REPLAY_STATE_PATHVOX_MESH_SCOPE_IDVOX_MESH_SERVER_STALE_PRUNE_MSVOX_MESH_TRAINVOX_MODELVOX_NEWS_PUBLISH_ARMEDVOX_NEWS_RSS_FEED_PATHVOX_NEWS_SITE_BASE_URLVOX_OPENAI_BASE_URLVOX_OPENCLAW_SIDECAR_DISABLEVOX_OPENCLAW_URLVOX_OPENCLAW_WS_URLVOX_OPENREVIEW_HTTP_MAX_ATTEMPTSVOX_ORCHESTRATOR_MESH_CONTROL_URLVOX_ORCHESTRATOR_PLAN_LLM_SYNTHESISVOX_ORCH_LINEAGE_OFFVOX_ORCH_METRICS_SINKVOX_PUBLISHER_DRY_RUNVOX_RATE_LIMIT_MAX_REQUESTSVOX_RATE_LIMIT_WINDOW_SECONDSVOX_RUNTIME_LLM_MAX_RETRYVOX_SCHOLARLY_ADAPTERVOX_SCHOLARLY_JOB_LOCK_OWNERVOX_SCHOLA_FORWARDVOX_SCHOLA_TRAIN_IN_PROCESSVOX_SCIENTIA_CROSSREF_MAILTOVOX_SEARCH_BM25_BVOX_SEARCH_BM25_K1VOX_SEARCH_DDG_FALLBACK_DISABLEDVOX_SEARCH_MAX_HOPSVOX_SEARCH_MEMORY_VECTOR_WEIGHTVOX_SEARCH_POLICY_VERSIONVOX_SEARCH_PREFER_RRFVOX_SEARCH_QDRANT_COLLECTIONVOX_SEARCH_QDRANT_URLVOX_SEARCH_QDRANT_VECTOR_NAMEVOX_SEARCH_REPO_MAX_FILESVOX_SEARCH_REPO_SKIP_DIRSVOX_SEARCH_RRF_KVOX_SEARCH_SCRAPER_MIN_DENSITYVOX_SEARCH_SCRAPER_ROBOTS_RESPECTVOX_SEARCH_SCRAPER_TIMEOUTVOX_SEARCH_SEARXNG_ENGINESVOX_SEARCH_SEARXNG_LANGUAGEVOX_SEARCH_SEARXNG_MAX_RESULTSVOX_SEARCH_SEARXNG_MAX_SCRAPEVOX_SEARCH_SEARXNG_URLVOX_SEARCH_TANTIVY_ROOTVOX_SEARCH_TAVILY_BUDGETVOX_SEARCH_TAVILY_DEPTHVOX_SEARCH_TAVILY_ENABLEDVOX_SEARCH_TAVILY_MAX_RESULTSVOX_SEARCH_TAVILY_ON_EMPTYVOX_SEARCH_TAVILY_ON_WEAKVOX_SEARCH_VERIFICATION_QUALITY_THRESHOLDVOX_SYNDICATION_TEMPLATE_PROFILEVOX_SYNTAX_K_TELEMETRYVOX_TRAIN_PROFILEVOX_TURSO_TOKENVOX_TURSO_URLVOX_UNIFIED_ROUTINGVOX_VRAM_OVERRIDE_GBVOX_WEB_RUN_MODEVOX_WEB_TANSTACK_STARTVOX_WORKFLOW_JOURNAL_CODEX_OFFVOX_ZENODO_API_BASEVOX_ZENODO_HTTP_MAX_ATTEMPTSVOX_ZENODO_STAGING_DIRVOX_ZENODO_UPLOAD_ALLOWLIST
Resolution Precedence
For each managed secret ID:
- canonical env name
- non-deprecated aliases (including opt-in
VOX_*aliases) - deprecated aliases (returns
DeprecatedAliasUsedstatus) - configured external backend (
infisicalorvault, when enabled) - secure local store
- compatibility file stores (
~/.vox/auth.json, legacy~/.vox/auth_token,.vox/populi/mesh.envwhere applicable)
Required vs Optional Model
vox clavis doctorevaluates blocking requirement groups (AnyOf/AllOf) per workflow/profile.Chat/Mcpblocking model in cloud mode is OpenRouter-first (OPENROUTER_API_KEY/VOX_OPENROUTER_API_KEY); alternate providers are optional capability keys.localmode requires no cloud key;autoresolves fromVOX_INFERENCE_PROFILE.- Optional keys are reported separately as capability unlocks (not startup blockers).
- OpenRouter does not replace RunPod/Vast keys: LLM gateway credentials and cloud GPU credentials are distinct domains.
Canonical Bundles
minimal_local_dev: zero required cloud keys.minimal_cloud_dev: OpenRouter only.gpu_cloud: RunPod or Vast key (plus Together optional).publish_review: GitHub token required; Zenodo / OpenReview / Crossref / arXiv-assist secrets optional (see inventory table).mesh_roles: worker or submitter mesh token (seeSecretBundle::MeshRoles/ SSOT mesh section).
Transition and Deprecation Window Policy
- Add alias support first (no breakage).
- Emit
DeprecatedAliasUsedin doctor for legacy aliases. - Keep legacy aliases for at least two release trains after warning lands.
- Remove legacy aliases from docs examples first; remove runtime support only after explicit release note and CI parity update.
Command Surfaces
vox clavis doctor --workflow <...> --profile <dev|ci|mobile|prod> --mode <auto|local|cloud> [--bundle <minimal-local-dev|minimal-cloud-dev|gpu-cloud|publish-review>]vox clavis set <registry> <token> [--username <name>]vox clavis get <registry>vox clavis backend-statusvox clavis migrate-auth-store- FORGE_TOKEN
- GH_TOKEN
- GITLAB_TOKEN
- GL_TOKEN
- GOOGLE_AI_STUDIO_KEY
- HUGGING_FACE_HUB_TOKEN
- POPULI_API_KEY
- TURSO_AUTH_TOKEN
- TURSO_URL
- VOX_ANTHROPIC_API_KEY
- VOX_CEREBRAS_API_KEY
- VOX_CROSSREF_PLUS_API_KEY
- VOX_CUSTOM_OPENAI_API_KEY
- VOX_DEEPSEEK_API_KEY
- VOX_FORGE_TOKEN
- VOX_GEMINI_API_KEY
- VOX_GROQ_API_KEY
- VOX_HF_TOKEN
- VOX_MISTRAL_API_KEY
- VOX_OPENAI_API_KEY
- VOX_OPENREVIEW_EMAIL
- VOX_OPENREVIEW_PASSWORD
- VOX_POPULI_API_KEY
- VOX_SAMBANOVA_API_KEY
- VOX_SOCIAL_REDDIT_CLIENT_ID
- VOX_SOCIAL_REDDIT_CLIENT_SECRET
- VOX_SOCIAL_REDDIT_REFRESH_TOKEN
- VOX_SOCIAL_REDDIT_USER_AGENT
- VOX_SOCIAL_YOUTUBE_CLIENT_ID
- VOX_SOCIAL_YOUTUBE_CLIENT_SECRET
- VOX_SOCIAL_YOUTUBE_REFRESH_TOKEN
- VOX_TOGETHER_API_KEY
- VOX_TURSO_TOKEN
- VOX_TURSO_URL
- VOX_V0_API_KEY
- VOX_WEBHOOK_INGRESS_TOKEN
- VOX_WEBHOOK_SIGNING_SECRET
- VOX_ZENODO_ACCESS_TOKEN
- VOX_SOCIAL_MASTODON_TOKEN
- VOX_SOCIAL_MASTODON_DOMAIN
- VOX_SOCIAL_LINKEDIN_ACCESS_TOKEN
- VOX_SOCIAL_DISCORD_WEBHOOK_URL