Onboarding wizard (revka onboard)

revka onboard is the first command you run after installing Revka. It creates your workspace, writes ~/.revka/config.toml, installs the Python MCP sidecars, and can start the daemon for you. The same command serves three jobs:

• Interactive wizard — a 9-step guided setup in a terminal (TTY).
• Quick setup — a zero-prompt path for CI, Docker, and scripted installs.
• Channel repair — re-run channel setup only, leaving everything else untouched.

Revka picks the mode automatically based on your terminal and the flags you pass, but you can force any mode explicitly. After onboarding completes, head to the Quickstart to send your first message.

Choosing a mode

Revka decides which path to run from your terminal state and flags:

Condition	Mode
--channels-only passed	Channel repair wizard
--quick passed, or any of --api-key / --provider / --model / --memory passed	Quick setup (non-interactive)
Interactive terminal (stdin + stdout are a TTY), or REVKA_INTERACTIVE=1	9-step interactive wizard
No TTY and no provider flags	Quick setup with defaults

Tip

Set REVKA_INTERACTIVE=1 to force the wizard even when there is no terminal (for example, inside a wrapper script). Provider flags always win — passing --api-key switches you to quick setup even in a TTY.

The interactive 9-step wizard

Run the wizard with no flags in a terminal:

revka onboard

Before Step 1 you see a bilingual language picker (“Select your language / 언어를 선택하세요”). It pre-selects whatever language is already active (from --lang, REVKA_LANG, or $LANG), so you can press Enter to accept it. The choice is saved to language in config.toml so later runs default to it.

The wizard then walks nine steps:

1. Workspace — creates ~/.revka/workspace/ and records the path in ~/.revka/active_workspace.toml so Revka finds it on every later run.
2. AI provider & API key — pick a provider and enter its API key. The wizard can fetch the provider’s live model catalog so you choose a real model ID.
3. Channels — configure messaging channels (Telegram, Discord, Slack, WhatsApp, Lark, and more). Allowlists default to deny-all; you must add yourself explicitly.
4. Tunnel — optionally expose the gateway publicly via Cloudflare, ngrok, Tailscale, and others. See Expose your gateway with a tunnel.
5. Tool mode — enable Composio managed OAuth tools and at-rest secrets encryption.
6. Hardware — optionally enable physical-world access over serial, native GPIO, or a debug probe.
7. Memory — choose a memory backend: SQLite, Kumiho cloud, Kumiho local Community Edition, Markdown, or none.
8. Project context — your name, timezone, the agent’s name, and communication style. These personalize the workspace files.
9. Workspace scaffolding — writes SOUL.md and AGENTS.md and seeds the built-in Operator workflow YAML templates.

The wizard defaults to Supervised autonomy with workspace-scoped access — see Autonomy levels & approvals and the Security model.

After the steps

Once the nine steps finish, the wizard:

• Offers to set up a DreamState memory-consolidation cron job (Kumiho backends only — see below).
• Writes a Kumiho service token to <workspace>/.env if you supplied one.
• Installs the Python MCP sidecars (Kumiho + Operator) so the setup is immediately usable. A declined or failed install is non-fatal — run revka install --sidecars-only later. See Install the Python MCP sidecars.
• Prints a summary, then offers to start Revka now (the daemon: gateway dashboard + channels + scheduler + heartbeat). Accepting runs revka daemon in the foreground so you see the one-time pairing code and dashboard URL.

If gateway.require_pairing is true (the default), the wizard prints next-step pairing instructions with your dashboard URL on completion. See Pairing & authentication.

Re-running with an existing config

If a config already exists and you run revka onboard without --force, the wizard enters a provider-only update mode. It re-prompts for provider, model, and API key, then writes only those fields back — channels, memory, tunnel, hooks, and every other setting are preserved. Use --force to bypass this and run the full 9-step wizard again.

Quick setup (non-interactive)

Quick setup (run_quick_setup) generates a sensible default config with no prompts. It is the recommended path for Docker, CI pipelines, and scripted bootstrap.

# Minimal: provider + key
revka onboard --api-key "sk-..." --provider openrouter

# With model and memory backend
revka onboard --api-key "sk-..." --provider anthropic \
  --model claude-sonnet-4-20250514 --memory kumiho

# Force quick setup with defaults (no provider flags)
revka onboard --quick

# Overwrite an existing config without prompting
revka onboard --api-key "sk-..." --provider openrouter --force

You can also drive it entirely from the environment:

REVKA_API_KEY="sk-..." REVKA_PROVIDER="openrouter" revka onboard --quick

Quick-setup defaults: provider openrouter, memory sqlite, temperature 0.7, gateway at 127.0.0.1 requiring pairing, no tunnel, no Composio.

Where the config is written: quick setup honors REVKA_CONFIG_DIR (entire config directory) and REVKA_WORKSPACE (workspace directory, from which the config dir is derived). Without either, it uses ~/.revka/.

Note

--channels-only cannot be combined with --api-key, --provider, --model, --memory, --force, or --quick. --reinit and --channels-only are also mutually exclusive.

Channel repair (--channels-only)

When a channel token rotates (for example a Telegram bot token) or an allowlist needs updating, re-run channel setup only — every other setting is preserved:

revka onboard --channels-only

This runs a fast single-step wizard that loads your existing config, re-runs Step 3 (Channels), and saves. If you have launchable channels and an API key configured, it then offers to launch channels immediately. Accepting sets REVKA_AUTOSTART_CHANNELS=1, which tells Revka to start the channel server as soon as the wizard returns.

See Connect a messaging channel for per-channel configuration.

Flags reference

Flag	Meaning
--force	Overwrite an existing config without confirmation, and run the full wizard instead of provider-only update mode.
--reinit	Back up the entire config directory (timestamped suffix) and onboard from scratch. The installed binary under bin/ is preserved. Cannot combine with --channels-only.
--channels-only	Run the fast channel-repair wizard only. Cannot combine with --api-key, --provider, --model, --memory, --force, or --quick.
--api-key <KEY>	Provider API key. Triggers quick setup.
--provider <ID>	Provider name, e.g. openrouter, anthropic, openai. Triggers quick setup. Default: openrouter.
--model <MODEL_ID>	Model override. Triggers quick setup.
--memory <kumiho|none>	Memory backend selection for quick setup.
--quick	Skip interactive prompts and use quick setup with defaults.
--lang <en|ko>	Wizard UI language. Overrides REVKA_LANG and $LANG.

Language selection

The wizard’s UI language is resolved with this priority: --lang flag → REVKA_LANG → $LC_ALL / $LANG → English. Supported values are en and ko.

revka onboard --lang ko          # wizard in Korean
REVKA_LANG=ko revka onboard      # same, via environment

The bilingual Step 0 picker can override this at runtime, and the final choice is persisted to language in config.toml.

--force vs --reinit

These two flags are easy to confuse:

• --force overwrites the current config in place without prompting (and skips the provider-only update path).
• --reinit moves your existing config and data into a timestamped backup directory (everything except the bin/ folder) and starts completely fresh. It prompts for y confirmation before backing up.

Config protection

Revka guards against accidental loss of your setup:

• A plain revka onboard over an existing config runs provider-only update mode rather than overwriting channels, memory, and the rest.
• In a non-interactive environment, you must pass --force to overwrite an existing config.
• --reinit always backs up before resetting, and asks for confirmation first.
• The sidecar install and DreamState steps are non-fatal: declining or failing them still leaves a valid config.

Caution

If you installed Revka with Homebrew, brew services defaults to a config under the Homebrew prefix (for example /opt/homebrew/var/revka/), which differs from the ~/.revka/ directory the wizard writes by default. The wizard prints a service note when these diverge — copy or link your workspace before running Revka as a service.

DreamState cron job offer

When you select a Kumiho memory backend, the wizard offers to schedule a nightly DreamState job. DreamState is Kumiho’s memory-consolidation cycle: it reviews recent memories, deprecates stale ones, enriches tags and metadata, and creates graph edges between related items.

You pick a run time:

Option	Cron expression
2:00 AM (quiet hours)	0 2 * * *
3:00 AM (default)	0 3 * * *
4:00 AM (early morning)	0 4 * * *
6:00 AM (before work)	0 6 * * *
12:00 AM (midnight)	0 0 * * *

The job runs the kumiho_memory_dream_state tool in an isolated session. You can add, change, or remove it later with revka cron:

revka cron list
revka cron update <id> --expression '0 4 * * *'

Learn more about graph memory in Kumiho graph memory.

Environment variables

Variable	Effect
REVKA_INTERACTIVE=1	Force the interactive wizard even without a TTY.
REVKA_AUTOSTART_CHANNELS=1	Start the channel server immediately after onboarding. Set automatically when you accept the “launch channels now?” prompt; you can also set it yourself.
REVKA_LANG=<en|ko>	Wizard UI language (lower priority than --lang).
REVKA_CONFIG_DIR=<PATH>	Override the entire config directory (used by quick setup).
REVKA_WORKSPACE=<PATH>	Override the workspace directory; the config directory is derived from it.
REVKA_API_KEY / REVKA_PROVIDER	Seed provider credentials non-interactively (triggers quick setup).

Workspace scaffolding

The final wizard step (and quick setup) creates the workspace layout that the agent and Operator rely on:

• ~/.revka/workspace/ — the active workspace, recorded in ~/.revka/active_workspace.toml.
• SOUL.md and AGENTS.md — identity and agent-instruction files personalized from your Step 8 answers.
• <workspace>/operator_mcp/workflow/builtins/ — built-in Operator workflow YAML templates.

You can re-seed the built-in workflows at any time (for example after an upgrade) without touching your config:

revka workflows list           # list bundled templates
revka workflows sync           # copy new templates (non-destructive)
revka workflows sync --force   # overwrite existing files

Next steps

Quickstart Send your first message and open the dashboard.

Install the Python MCP sidecars Kumiho + Operator sidecars for memory and orchestration.

Run the dashboard Pair a client and explore the web UI.

Configuration overview Every config.toml key, default, and env override.