roboco/docs/rag/architecture/config-reference.md

Configuration Reference

Environment variables for RoboCo (prefix: ROBOCO_).

API Server

Variable	Default	Description
ROBOCO_HOST	127.0.0.1	API host (0.0.0.0 for containers)
ROBOCO_PORT	8000	API port
ROBOCO_DEBUG	false	Debug mode
ROBOCO_ENVIRONMENT	development	development/staging/production

Database

Variable	Default	Description
ROBOCO_DATABASE_HOST	localhost	PostgreSQL host
ROBOCO_DATABASE_PORT	5432	PostgreSQL port
ROBOCO_DATABASE_USER	roboco	Database user
ROBOCO_DATABASE_PASSWORD	roboco	Database password
ROBOCO_DATABASE_NAME	roboco	Database name

Redis

Variable	Default	Description
ROBOCO_REDIS_HOST	localhost	Redis host
ROBOCO_REDIS_PORT	6379	Redis port
ROBOCO_REDIS_DB	0	Redis database

Workspaces

Variable	Default	Description
ROBOCO_WORKSPACES_ROOT	/data/workspaces	Root for agent workspaces
ROBOCO_WORKSPACE_AUTO_CLONE	true	Auto-clone on first access
ROBOCO_WORKSPACE_CLONE_TIMEOUT	300	Clone timeout (seconds)

RAG/Embeddings

Variable	Default	Description
ROBOCO_DEFAULT_EMBEDDING_MODEL	qwen3-embedding:0.6b	Embedding model
ROBOCO_EMBEDDING_DIMENSIONS	1024	Embedding dimensions
ROBOCO_RAG_CHUNK_STRATEGY	fixed	fixed/semantic/hierarchical/contextual
ROBOCO_RAG_CHUNK_SIZE	512	Base chunk size
ROBOCO_RAG_CHUNK_SIZE_DOCS	1536	Chunk size for docs
ROBOCO_RAG_CHUNK_SIZE_JOURNALS	1024	Chunk size for journals
ROBOCO_RAG_CHUNK_OVERLAP	128	Chunk overlap
ROBOCO_RAG_USE_HYBRID_SEARCH	true	BM25 + vector search
ROBOCO_RAG_USE_CROSS_ENCODER	true	Neural reranking
ROBOCO_RAG_AUTO_UPDATE_ENABLED	true	Auto-update indexes
ROBOCO_RAG_AUTO_UPDATE_INTERVAL	300	Update interval (seconds)

LLM

Variable	Default	Description
ROBOCO_LOCAL_LLM_MODEL	glm-5.2:cloud	Local LLM for RAG
ROBOCO_LOCAL_LLM_BASE_URL	http://roboco-ollama:11434/v1	OpenAI-compat API
ROBOCO_OLLAMA_BASE_URL	http://roboco-ollama:11434	Native Ollama API

Grok provider (xAI)

Agents whose provider is GROK run xAI's official grok CLI. Auth is the host SuperGrok subscription (mounted ~/.grok), not a metered API key.

Variable	Default	Description
ROBOCO_HOST_GROK_DIR	~/.grok	Host dir holding auth.json, mounted into Grok agents; the orchestrator auto-refreshes the ~6h token in place. Set up once with grok login.
ROBOCO_GROK_CLI_MODEL	grok-build	Grok CLI model id
ROBOCO_GROK_AGENT_IMAGE	roboco-agent-grok:latest	Image for Grok delivery agents
ROBOCO_GROK_REASONING_EFFORT	(blank)	Per-run reasoning-effort override; blank = the grok CLI default
ROBOCO_GROK_IDLE_KILL_SECONDS	900	Kill + evict a Grok container that has been ACTIVE-yet-idle (no gateway verb) this long
ROBOCO_GROK_MAX_COST_USD	0.0	Per-agent Grok cost ceiling (USD); 0 disables

Kimi provider (Moonshot AI)

Agents whose provider is KIMI run Moonshot AI's official kimi (kimi-code) CLI. Auth is the host Kimi subscription (OAuth device-code login via kimi login), not a metered API key — the credential dir is mounted read-write and shared across every Kimi agent plus the orchestrator, since Moonshot's refresh token is rotation-with-short-reuse-grace rather than truly reusable.

Variable	Default	Description
ROBOCO_HOST_KIMI_DIR	~/.kimi-code	Host dir holding credentials//oauth/, mounted read-write and shared across every Kimi agent; the CLI's own cross-process lock serializes token redemptions. Set up once with kimi login.
ROBOCO_KIMI_CLI_MODEL	kimi-code/k3	Kimi CLI model alias; kimi-code/kimi-for-coding is the cheaper cost lever
ROBOCO_KIMI_RATE_LIMIT_RETRY_AFTER_SECONDS	60	Park-and-retry delay after a rate-limit/quota sniff (exit 75)
ROBOCO_KIMI_AUTH_RETRY_AFTER_SECONDS	60	Park-and-retry delay after a missing/expired credential (exit 78)

Feature flags

Env-gated subsystems. Most are default-off; ROBOCO_OVERLOAD_BREAK_ENABLED, ROBOCO_RESEARCH_ENABLED, and ROBOCO_PROVISIONING_ENABLED ship default-on. Each takes effect on the next backend restart; the panel's Settings → Feature Flags card toggles the panel-exposed ones (roboco/services/settings.py's FEATURE_FLAGS) without hand-editing env — a few security/topology flags below are env-only by design and are called out as such.

The PR-gate turn cut (when every child of an assembled parent is terminal, _try_auto_submit runs the real submit_up / submit_root system-side as the owning PM instead of spawning the PM for that turn) is unconditional — no flag, no kill-switch. A gate rejection (freshness/integrity/AC-coverage/a subtask-terminal race) or transport error falls back to the classic PM closure spawn with the rejection reason threaded into the PM's prompt; that fallback is the sole safety net. Each auto-submit leaves a task.auto_submitted audit row.

Variable	Default	Description
ROBOCO_CONVENTIONS_ENABLED	false	Architectural Conventions Standard: auto-scaffold .roboco/conventions.yml, inject the architecture map, attach baseline constraints, and block i_am_done / pr_pass on block-level placement and hygiene violations. Off = fully inert.
ROBOCO_TOOLCHAIN_MATCH_ENABLED	false	Provision each agent workspace with the target project's Python (resolved from its requires-python / .python-version) and block delivery gates when the suite cannot be executed under it. Off = today's behavior.
ROBOCO_OVERLOAD_BREAK_ENABLED	true	Park a provider on a persistent model-API overload (HTTP 529 / 500 / 503) the same way a 429 is parked — queue its spawns and probe until it recovers — instead of crash-retrying into the overload. Off = crash-retry behavior.
ROBOCO_SPAWN_PREFLIGHT_ENABLED	false	Refuse to spawn a non-human delivery role absent from GATEWAY_ENABLED_ROLES (no manifest → can never claim → would respawn on the same task forever); refuse + alert the overseer once instead. Inert in practice (all delivery roles are gateway-enabled). Armed on the NAS composes.
ROBOCO_NOTIFICATION_SPAWN_COOLDOWN_SECONDS	600	Cross-tick damper for notification-triggered spawns (escalation/approval/audit/a2a — task-less, so the readiness gate and respawn breaker never see them): one spawn per (agent, notification) per window; the notification stays pending so the next window retries. 0 = legacy every-tick respawn.
ROBOCO_SANDBOX_DB_ENABLED	false	Sandboxed per-agent-spawn test DB/Redis/Mongo: throwaway sibling containers provisioned from the engine registry in roboco/models/sandbox.py (postgres:16-alpine / redis:8-alpine / mongo:8), per-project opt-in. The valid-service set is VALID_SANDBOX_SERVICES (registry-derived). See "Sandboxed Dev DB/Redis/Mongo" below and docs/rag/architecture/sandbox-db.md.
ROBOCO_X_ENGINE_ENABLED	false	The X (Twitter) engine: draft release/mention posts, ALL held for per-post CEO approval. See "X (Twitter) Engine" below and docs/rag/architecture/x-engine.md.
ROBOCO_ROADMAP_ENGINE_ENABLED	false	Legacy alias for the roadmap Board Program (Printer): weekly Product-Owner-authored cycle, CEO approves each item individually into BACKLOG. See "Board Program Registry" below and docs/rag/architecture/board-programs.md.
ROBOCO_OBSIDIAN_VAULT_ENABLED	false (both compose files set true)	The Obsidian vault projection: tasks/journals/A2A become wikilinked markdown, rebuildable from the DB. See docs/rag/architecture/obsidian-vault.md.
ROBOCO_VAULT_INTAKE_ENABLED	false (both compose files set true)	The vault's #roboco-tag inbox watcher — requires ROBOCO_OBSIDIAN_VAULT_ENABLED also on. See docs/rag/architecture/obsidian-vault.md.
ROBOCO_VAULT_ARCHIVE_DAYS	30 (0 disables)	Age (past its terminal timestamp) a completed/cancelled task's note must reach before the vault janitor moves it to RoboCo/Archive/<year>/.
ROBOCO_VAULT_REPORT_ENABLED	true	The vault janitor's weekly RoboCo/Reports/<ISO-week>.md org-report note + CEO notification (deterministic, no LLM). Needs ROBOCO_OBSIDIAN_VAULT_ENABLED also on.
ROBOCO_VAULT_KB_ENABLED	false (NAS compose sets true; registry compose leaves false)	Master switch for vault KB ingest: embeds ROBOCO_VAULT_KB_DIRS note folders (default RoboCo/Notes) into IndexType.VAULT_NOTES, screened for injection attempts before indexing. Requires ROBOCO_OBSIDIAN_VAULT_ENABLED also on. ROBOCO_VAULT_KB_DIRS (CSV, default RoboCo/Notes) and ROBOCO_VAULT_KB_INTERVAL_SECONDS (default 900) tune scope and cadence. See docs/rag/architecture/obsidian-vault.md.

The company-in-a-box subsystems toggle the same way: web research (ROBOCO_RESEARCH_ENABLED, default on — see "Web Research" below), the strategy engine (ROBOCO_STRATEGY_ENGINE_ENABLED, default off), and pitch provisioning (ROBOCO_PROVISIONING_ENABLED, default on but inert without a token/org configured).

Web Research

Pluggable external search/fetch for the Board + PM roles (cell_pm, main_pm, product_owner, head_marketing). Calls flow agent → roboco-search MCP → /api/research/* → ResearchService → provider; the provider key lives only in the server-side process — it is never injected into an agent container, and agents never egress (the provider's own API does). See docs/rag/tools/research-tools.md for the web_search / web_fetch tool contract.

Variable	Default	Description
ROBOCO_RESEARCH_ENABLED	true	Master switch. Ships default-on (unlike most feature flags): the roboco-search MCP server is mounted for the four research roles unless explicitly disabled. Panel-toggleable. Both NAS composes also set ROBOCO_RESEARCH_ENABLED:-true explicitly (redundant with the code default, but keeps the deploy's env self-documenting).
ROBOCO_RESEARCH_PROVIDER	tavily	Adapter: tavily (LLM-native cited results + extract), brave (independent index, no fetch endpoint), exa (neural search + contents), or null (always-empty stub). Swapping providers is a config change only.
ROBOCO_RESEARCH_API_KEY	(unset)	API key for the selected provider. Server-side only. Unset ⇒ graceful NullProvider (empty results, never a hard fail).
ROBOCO_RESEARCH_MAX_RESULTS	5	Hard cap (1-20) on web_search results per call.
ROBOCO_RESEARCH_FETCH_MAX_CHARS	20000	Hard cap on characters web_fetch returns; content past this is truncated.
ROBOCO_RESEARCH_TIMEOUT_SECONDS	15.0	Per-request timeout for outbound provider HTTP calls.
ROBOCO_RESEARCH_DAILY_QUOTA_PER_AGENT	50	Max web_search + web_fetch calls per agent per UTC day. Tracked in Redis; fails open (allows the call) if Redis is unreachable.

Self-Healing CI loop

RoboCo watching its own repo's CI. All default-off / dormant.

Variable	Default	Description
ROBOCO_SELF_HEAL_ENABLED	false	Master switch (detect + notify the CEO); off = the loop never runs and no CI is fetched
ROBOCO_SELF_HEAL_ORIGINATE_ENABLED	false	Second opt-in: also open a PENDING fix task on a regression — CEO-gated, never auto-started/merged/deployed
ROBOCO_SELF_HEAL_PROJECT_SLUG	(empty)	The registered project that IS RoboCo itself — the only repo it watches and fixes; empty = no-op
ROBOCO_SELF_HEAL_CI_WORKFLOW	(empty)	GitHub Actions workflow to scope the CI signal to (e.g. ci.yml); empty = latest across all workflows
ROBOCO_SELF_HEAL_INTERVAL_SECONDS	1800	Seconds between assessment passes
ROBOCO_SELF_HEAL_MAX_OPEN_TASKS	3	Rolling cap on concurrently-open self-heal tasks
ROBOCO_SELF_HEAL_MAX_PER_CYCLE	1	Max fix tasks originated per cycle

Autonomous maintenance

The fan-out generalizations of self-heal — they watch any opted-in project, not just RoboCo's own. All default-off; neither ever auto-merges (every task rides the normal delivery + PR-review gate). Per-project opt-in lives on the project row (set in the panel's edit-project dialog), not in env.

Variable	Default	Description
ROBOCO_CI_WATCH_ENABLED	false	Master switch for multi-repo CI-watch; off = the loop never runs. Per-project opt-in via projects.ci_watch_enabled
ROBOCO_CI_WATCH_DEFAULT_WORKFLOW	ci.yml	Workflow file the CI signal is scoped to when a project sets no ci_watch_workflow
ROBOCO_CI_WATCH_INTERVAL_SECONDS	1800	Seconds between CI-watch passes
ROBOCO_CI_WATCH_MAX_OPEN_TASKS	3	Rolling cap on concurrently-open ci_watch tasks
ROBOCO_CI_WATCH_MAX_PER_CYCLE	1	Max ci_watch fix tasks originated per cycle
ROBOCO_DEP_UPDATE_ENABLED	false	Master switch for the dependency-update bot; off = the loop never runs. Per-project opt-in via projects.dep_update_command
ROBOCO_DEP_UPDATE_INTERVAL_SECONDS	604800	Seconds between dependency-update passes (default weekly)
ROBOCO_DEP_UPDATE_MAX_OPEN_TASKS	3	Rolling cap on concurrently-open dep_update tasks
ROBOCO_DEP_UPDATE_MAX_PER_CYCLE	1	Max dep_update tasks originated per cycle
ROBOCO_RELEASE_MANAGER_ENABLED	false	Master switch for the gated release manager; off = the loop never runs. Even on it only PROPOSES — the CEO approves before any publish
ROBOCO_RELEASE_MIN_COMMITS	8	Minimum unreleased commits since the last tag before a release is proposed (a feat/security change also qualifies)
ROBOCO_RELEASE_MANAGER_INTERVAL_SECONDS	3600	Seconds between release-readiness assessment passes
ROBOCO_DOCS_SYNC_ENABLED	false	Master switch for the docs-divergence sync engine. When on, a successful release publish originates one bounded, deduped docs-update task per release tag against the roboco-website project. Requires roboco-website to be registered as a project; otherwise the engine logs a warning and no-ops. Panel-toggleable via FEATURE_FLAGS. The NAS compose defaults it to true; the local and registry composes default it to false.
ROBOCO_DOCS_SYNC_MAX_OPEN_TASKS	3	Rolling cap on concurrently-open docs-sync tasks; the engine originates nothing more while this many are still open.
ROBOCO_DOCS_SYNC_MAX_PER_CYCLE	1	Max docs-sync tasks the engine may originate in one invocation. A release publish is a single invocation, so this bounds it to one task per publish event.
ROBOCO_ORG_MEMORY_ENABLED	false	Master switch for the org-memory loop (distill at completion, index journals, auto-inject lessons/playbooks); off = legacy capture, no inject
ROBOCO_ORG_MEMORY_TOP_K	3	Max institutional-memory items injected into a briefing on claim
ROBOCO_ORG_MEMORY_MIN_SCORE	0.6	Cosine-similarity floor for injected memory; below it nothing is injected
ROBOCO_IMAGE_PRUNE_ENABLED	true	Background sweep prunes dangling (<none>) Docker images from agent-image rebuilds (only dangling; ~6h throttle). Always-on safety net, not a feature flag
ROBOCO_IMAGE_PRUNE_INTERVAL_SECONDS	21600	Minimum seconds between dangling-image prune passes

Sandboxed Dev DB/Redis/Mongo

Per-agent-spawn throwaway Postgres/Redis/Mongo, replacing (never coexisting with) the legacy prod-creds gate-env injection for an opted-in project. Default-off; see docs/rag/architecture/sandbox-db.md.

Variable	Default	Description
ROBOCO_SANDBOX_DB_ENABLED	false	Master switch. Off = spawning behaves exactly as today (the legacy _append_gate_env prod-creds injection, itself gated by ROBOCO_TOOLCHAIN_MATCH_ENABLED). Only projects with their sandbox_services column set (migration 057) participate even when on. The valid service set is VALID_SANDBOX_SERVICES in roboco/models/sandbox.py (registry-derived: postgres / redis / mongo); adding an engine is one class + one registry line, no orchestrator edit. Env injected per engine: ROBOCO_TEST_DB_*, ROBOCO_TEST_REDIS_*, ROBOCO_TEST_MONGO_* (incl. ROBOCO_TEST_MONGO_AUTH_DB=admin). A project may also declare sandbox_extensions (migration 072) — a per-service extension/module map activated post-ready via docker exec, bounded by a fixed allowlist (SANDBOX_PG_EXTENSIONS / SANDBOX_REDIS_MODULES; no plpython3u). See docs/rag/architecture/sandbox-db.md.

X (Twitter) Engine

Drafts release-announcement and mention-reply posts, ALL held for per-post CEO approval — nothing ever posts automatically. Default-off; see docs/rag/architecture/x-engine.md.

Variable	Default	Description
ROBOCO_X_ENGINE_ENABLED	false	Master switch. Off = no draft is originated and no X API call is ever made. Even on, posting requires stored credentials (panel-entered) AND an explicit per-post CEO approval.
ROBOCO_X_REPLIES_ENABLED	false	Sub-switch for the mention-reply half. Off (even with the engine on) = the engine only drafts release-announcement posts; it never polls mentions or drafts replies. Reading mentions needs a paid X API tier, so replies are a deliberate opt-in on top of release posting.
ROBOCO_X_MENTIONS_INTERVAL_SECONDS	1800	Seconds between mentions-poll passes (only when X_REPLIES_ENABLED).
ROBOCO_X_MENTIONS_MAX_PER_CYCLE	5	Max held reply proposals the mentions poll may originate in one cycle.
ROBOCO_X_MENTIONS_MIN_ENGAGEMENT	0	Minimum like+reply+retweet count for a mention to count as "meaningful" (the engagement half of the mention filter; the other half rejects bare retweets and near-empty text).
ROBOCO_X_MAX_OPEN_POSTS	10	Rolling cap on concurrently-open held X posts/replies (both sources combined); the engine originates nothing more past it.
ROBOCO_X_ACCOUNT_USER_ID	(empty)	Numeric X user id of the account's own account. Empty resolves it once per mentions cycle via GET /2/users/me (one extra call).
ROBOCO_X_REQUEST_TIMEOUT_SECONDS	15.0	Per-request timeout for outbound X API HTTP calls.

Board Program Registry

Fourteen registered programs (Printer/roadmap, feature-spotlight, and twelve new ones across Product Owner / Head of Marketing / Auditor) ride one generic registry + engine instead of bespoke per-engine loops. Every artifact is HELD; the CEO is the only path to materialization. See docs/rag/architecture/board-programs.md for the full lifecycle, the fourteen-program catalog, and each role's exact propose_* call shape.

Arming has no master flag. Each program is armed independently through a settings-store row (board_program.{key}.enabled, toggled from the panel's Board Programs page, Business section) — roadmap and x_feature additionally accept their pre-existing legacy env flags as a fallback when no settings-store row exists yet (byte-for-byte migration); every other program is settings-store-only and defaults OFF.

Variable	Default	Description
ROBOCO_ROADMAP_ENGINE_ENABLED	false	Legacy fallback for the roadmap program only (see above).
ROBOCO_ROADMAP_INTERVAL_SECONDS	604800	Seconds between roadmap-exploration cycles (default weekly) when no settings-store interval override is set.
ROBOCO_ROADMAP_MIN_ITEMS_PER_CYCLE	3	Minimum roadmap item drafts a themed cycle must propose.
ROBOCO_ROADMAP_MAX_ITEMS_PER_CYCLE	7	Maximum roadmap item drafts a themed cycle may propose.
ROBOCO_PEST_REWORK_THRESHOLD	0.3	The one compose-settable knob among the twelve new programs: the 7-day rework rate above which Pest Control's metric predicate opens a cycle off-schedule, on top of its weekly cron. Every other new program has no env knob at all — cadence overrides, when set, also live in the settings store.

No dedicated migration for a cycle's own payload — a cycle is marker-backed (orchestration_markers on the held exploration task) for every program, not a new table per program. The shared LEARN ledger (board_program_cycles, migration 087) and the per-project scoping column (projects.board_programs, migration 088) are the only new tables/columns.

Possibilities Matrix

The work-already-done fast path on i_am_done. Default-off, transparent to the dev (no verb change, no opt-in call). See docs/rag/architecture/possibilities-matrix.md.

Variable	Default	Description
ROBOCO_POSSIBILITIES_MATRIX_ENABLED	false	Master switch. Off = i_am_done behaves exactly as it always has. On = when a task already has commits, an open PR, every AC addressed, and no open findings, i_am_done submits straight to awaiting_qa, trusting the PR's own CI-green signal (falling back to the local make quality gate when there's no CI signal, and refusing outright on a known-red CI).

Cloud Auth

Not a panel feature flag — unlike the flags above, ROBOCO_CLOUD_AUTH_ENABLED is env-only (deliberately absent from roboco/services/settings.py's FEATURE_FLAGS, so it can't be flipped on for a deployment that isn't behind TLS). Lets the panel/API be exposed beyond localhost without changing the CEO's local no-login flow while off. See docs/rag/architecture/cloud-auth.md.

Variable	Default	Description
ROBOCO_CLOUD_AUTH_ENABLED	false	Master switch. Off: get_agent_context behaves byte-for-byte as today (header-trust). On: no registration router is mounted — exactly one user, seeded from cloud_auth_email / cloud_auth_password. Fails loud at startup (raises before the app boots) if true without ROBOCO_CLOUD_AUTH_SECRET set.
ROBOCO_CLOUD_AUTH_EMAIL	(unset)	Email for the single seeded CEO login user.
ROBOCO_CLOUD_AUTH_PASSWORD	(unset)	Password for the single seeded user. Hashed at startup; never stored in plain text.
ROBOCO_CLOUD_AUTH_SECRET	(unset)	Session-signing secret for the login cookie's JWT. Required when enabled — generate with python -c 'import secrets; print(secrets.token_hex(32))'.
ROBOCO_CLOUD_AUTH_COOKIE_MAX_AGE	2592000	Session cookie lifetime in seconds (30 days). Sliding: every authenticated request re-mints + re-sets the cookie, so an active session never expires — only genuine inactivity past this window logs out.

The session cookie is secure-only (cookie_secure=True in roboco/api/auth/backend.py) — arm this flag only behind TLS, or the browser will silently refuse to send the cookie and login will appear to fail.

DB Network Isolation

Not a panel feature flag — ROBOCO_DB_NETWORK_ISOLATED must travel with the compose file's networks: stanzas (it describes topology, not a runtime-toggleable behavior), so it is env-only like ROBOCO_CLOUD_AUTH_ENABLED.

Variable	Default	Description
ROBOCO_DB_NETWORK_ISOLATED	false	Set true by the compose files that put postgres/redis on the data-only roboco_data network agents never join. Suppresses the legacy _append_gate_env prod-creds injection (unreachable creds are worse than none) — DB-needing projects use the sandbox opt-in instead.

Security

Variable	Default	Description
ROBOCO_ENCRYPTION_KEY	(required)	Fernet key that encrypts secrets at rest (e.g. per-project git tokens, the x_credentials OAuth 1.0a singleton row). Generate with Fernet.generate_key().
ROBOCO_AGENT_AUTH_SECRET	(required)	HMAC secret the orchestrator signs each agent's X-Agent-Token with.
ROBOCO_AGENT_AUTH_REQUIRED	false	When true, every request must carry a valid agent token (secure mode).
ROBOCO_PANEL_AGENT_TOKEN	(unset)	The control panel's CEO token, injected by nginx in secure mode. Get it with make panel-token.

ROBOCO_ENCRYPTION_KEY also encrypts the x_credentials row (the four X/Twitter OAuth 1.0a secrets) — the same key, one more consumer.