Configuration overview

Revka is configured through a single TOML file, config.toml, that lives in your Revka directory (by default ~/.revka/config.toml). One file holds everything: the default provider and model, gateway and security policy, memory backend, channel tokens, tools, and the sidecar integrations. This page is the map of that file — how Revka decides which config.toml to load, the core top-level keys you edit first, how to export the machine-readable schema, the full section catalog, and which keys are hot-reloaded without a restart.

Use this page as the entry point to the configuration reference. The provider, channel, tool, and platform/security sections each have their own dedicated pages, linked from the section catalog below. Environment-variable overrides — the .env loading order and the complete REVKA_* table — live on the CLI overview page; this page summarizes the ones that affect file resolution and cross-links the rest.

Config file resolution order

When you do not pass the global --config-dir flag (or its backing REVKA_CONFIG_DIR variable), Revka resolves which config.toml to load through a three-level precedence chain:

1. REVKA_WORKSPACE — if this environment variable is set, the workspace directory it names wins absolutely, and the config directory is derived from it.
2. ~/.revka/active_workspace.toml — a persisted marker file written by revka onboard that points at the selected workspace. This is why your workspace path persists between runs without re-specifying it.
3. Default — ~/.revka/config.toml.

REVKA_CONFIG_DIR (and the --config-dir flag it backs) overrides the entire config directory and is applied before the config file is loaded, since it determines which file to load in the first place. --config-dir must come before the subcommand, and an empty string is rejected.

# Explicit config directory (flag also sets REVKA_CONFIG_DIR for child processes)
revka --config-dir /srv/revka daemon

# Workspace override via environment
REVKA_WORKSPACE=/data/workspace revka agent

Caution

Homebrew installs default to /opt/homebrew/var/revka/, which differs from the ~/.revka/ directory a manual install uses. revka onboard warns when the config it writes diverges from the path your service runs against — copy or link your workspace before running Revka as a service. See the macOS lifecycle page.

REVKA_WORKSPACE and REVKA_CONFIG_DIR

The two file-location variables are distinct:

Variable	Overrides	Behavior
REVKA_CONFIG_DIR	the --config-dir flag	Overrides the whole config directory. Read before the config file is loaded. Setting the --config-dir flag also exports this variable for any child process Revka spawns.
REVKA_WORKSPACE	the active workspace directory	Points at the workspace; the config directory is derived from it. Wins over the active_workspace.toml marker.

The first run (revka onboard) creates the workspace, writes config.toml, and records the chosen workspace in active_workspace.toml. See the Onboarding wizard for the full first-run flow.

active_workspace.toml

~/.revka/active_workspace.toml is a small marker file written by revka onboard (step 2 of the wizard). It records the path to the workspace you selected, so subsequent runs load the same workspace and its config.toml without you setting REVKA_WORKSPACE every time. It is the second rung of the resolution chain: REVKA_WORKSPACE overrides it, and it overrides the bare ~/.revka/config.toml default.

Note

active_workspace.toml (a workspace pointer written automatically) is unrelated to the [workspace] config section, which controls multi-client workspace isolation profiles. See Config: gateway, memory, security & platform for the [workspace] section.

Core top-level config keys

These are the keys at the root of config.toml — the first things you edit after onboarding. Every one of them can also be set through revka onboard or an environment variable.

# ~/.revka/config.toml — core top-level keys
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4.6"
default_temperature = 0.7
provider_timeout_secs = 120
# api_key = "sk-..."          # prefer a provider env var or secrets encryption
# api_url = "http://10.0.0.1:11434"   # provider base-URL override (e.g. Ollama)
# language = "en"
# locale = "en-US"

Key	Type	Default	Notes
api_key	String?	none	Provider API key. Overridden by REVKA_API_KEY / API_KEY, or a provider-specific env var. Prefer not to store it in cleartext — see [secrets].
api_url	String?	none	Provider base-URL override (e.g. Ollama at http://10.0.0.1:11434).
api_path	String?	none	Custom API path suffix (e.g. /v2/generate).
default_provider	String	"openrouter"	Default model provider. Accepts the alias model_provider. Env: REVKA_PROVIDER, or legacy PROVIDER.
default_model	String	"anthropic/claude-sonnet-4.6"	Default model. Accepts the alias model. Env: REVKA_MODEL.
default_temperature	f64	0.7	Valid range 0.0–2.0. Env: REVKA_TEMPERATURE.
provider_timeout_secs	u64	120	HTTP timeout for LLM provider calls, in seconds.
provider_max_tokens	u32?	unset	Overrides the provider’s default output-token limit. Important for OpenRouter, whose 65536 default can cause 402 errors on some models.
extra_headers	Map<String,String>	{}	Extra HTTP headers for provider calls. Env: REVKA_EXTRA_HEADERS in Key:Value,Key2:Value2 format.
language	String?	auto-detected	UI language for the wizard and interactive surfaces: "en" or "ko". Priority: --lang > REVKA_LANG > this field > LC_ALL/LANG > English.
locale	String?	auto-detected	Locale for tool descriptions (separate from language; supports a wider set such as zh-CN, ja-JP). Env: REVKA_LOCALE.

Note

language and locale are different fields. language controls only the wizard/interactive UI and accepts en/ko. locale controls the locale of LLM-facing tool descriptions and accepts a wider range. The legacy PROVIDER variable only overrides the config default when the config still reads openrouter; REVKA_PROVIDER always wins when set.

For the full provider env-var precedence (explicit api_key → provider-specific env var → generic REVKA_API_KEY) and the complete REVKA_* table, see the CLI overview.

revka config schema

revka config schema dumps the machine-readable JSON Schema (draft 2020-12) for the entire config.toml contract to stdout. The schema documents every available key, its type, default, and description, making it the authoritative source of truth for the config format — broader than this page, which covers the keys you reach for most.

revka config schema                 # print to stdout
revka config schema > schema.json   # save for tooling

The most common use is editor validation: point your editor’s JSON-Schema support at the exported file to get autocompletion and inline validation while you edit config.toml. In VS Code with the Even Better TOML extension, for example:

.vscode/settings.json

{
  "evenBetterToml.schema.associations": {
    ".*/config\\.toml$": "./schema.json"
  }
}

This command needs no running daemon and makes no network calls; it does load your existing config directory.

Section catalog

Below the core keys, config.toml is organized into named sections (TOML tables). Each is documented in detail on a dedicated reference page:

Provider, agent & routing [model_providers], [agent], [pacing], [reliability], [[model_routes]], [[embedding_routes]], [query_classification], [agents.], [swarms], [delegate].

Channels, tools & integrations [channels_config], [mcp], [browser], [http_request], [web_search], [composio], [google_workspace], [transcription], [tts], [multimodal], and more.

Gateway, memory, security & platform [gateway], [tunnel], [proxy], [memory], [kumiho], [operator], [autonomy], [security.otp], [security.estop], [workspace], [secrets], [storage], [cost], [observability].

Cargo feature flags & ADRs Which sections require a compiled-in feature flag (e.g. browser-native, hardware, observability-otel).

A few sections are gated behind a compiled-in Cargo feature flag — for example [browser]’s rust-native backend needs browser-native, [hardware] needs hardware, and OpenTelemetry support in [observability] needs observability-otel. See Cargo feature flags & ADRs.

Hot-reload behavior

A subset of keys is hot-reloaded while the daemon and channels are running — Revka watches config.toml and applies these on the next inbound channel message, with no restart required. The hot-reloaded keys are:

• default_provider
• default_model
• default_temperature
• api_key / api_url
• reliability.* (retries and fallback providers)

# Editing any of these and saving applies on the next inbound message:
default_provider = "anthropic"
default_model = "claude-sonnet-4-6"
default_temperature = 0.4

[reliability]
fallback_providers = ["openai"]

Every other section requires restarting the daemon (revka service restart, or stop and re-run revka daemon) to take effect.

Caution

Hot-reload applies to the daemon and channel runtime. The interactive revka agent session does not hot-reload config — restart the session to pick up changes. You can also switch provider and model live from within a chat session using the in-chat runtime commands (/models, /model <model-id>, /new); see revka channel & integrations.

Examples

Locate the config

# Workspace override wins absolutely
REVKA_WORKSPACE=/data/workspace revka status

# Force a specific config directory for one command
revka --config-dir /srv/revka doctor

# Inspect the marker that records your selected workspace
revka status   # prints the active workspace and provider/model in use

Edit core keys

# Quick, non-interactive provider/model/key setup
revka onboard --api-key "sk-..." --provider openrouter \
  --model "anthropic/claude-sonnet-4-6"

# Or set just the default model directly in config.toml
revka models set anthropic/claude-sonnet-4.6

Validate with the schema

revka config schema > schema.json
# point your editor at schema.json for config.toml autocompletion

Next steps

CLI overview & environment The --config-dir flag, .env loading order, and the complete REVKA_* environment-variable reference.

Config: provider, agent & routing Default provider/model, named provider profiles, routing, fallback, and sub-agents.

Config: gateway, memory, security & platform Gateway, tunnel, proxy, memory/Kumiho, autonomy, OTP, e-stop, and workspace isolation.

Onboarding wizard The revka onboard walkthrough that writes config.toml and active_workspace.toml.