revka install, update, migrate, completions & ACP

This page covers the lifecycle and integration commands that sit around a running Revka instance: installing the Python MCP sidecars, keeping the binary up to date, migrating in from another runtime, launching the companion desktop app, managing optional WASM plugins, generating shell completions, and exposing Revka over the ACP stdio protocol.

Most of these are commands you run once during setup or on a schedule — not in your day-to-day agent loop. For first-time setup, start with Installation and the Onboarding wizard; for the broader command surface, see the CLI overview.

revka install (sidecars)

revka install provisions Revka’s Python MCP sidecars — the Kumiho MCP client (graph memory) and the Operator MCP (workflows and orchestration). The full from-scratch install is handled by install.sh; the CLI command currently requires the --sidecars-only flag.

revka install --sidecars-only
revka install --sidecars-only --dry-run                  # preview actions (POSIX only)
revka install --sidecars-only --python /opt/homebrew/bin/python3
revka install --sidecars-only --with-session-manager
revka install --sidecars-only --from-source /path/to/Revka
revka install --sidecars-only --skip-kumiho --skip-operator

Flag	Meaning
--sidecars-only	Required. Installs the Kumiho + Operator Python MCP sidecars.
--skip-kumiho	Skip the Kumiho MCP sidecar.
--skip-operator	Skip the Operator MCP sidecar.
--with-session-manager	Also install the Node.js Session Manager sidecar (requires npm; see the cost note below).
--dry-run	Print the planned actions without executing them (POSIX only).
--python <PATH>	Use an explicit Python interpreter instead of auto-detection.
--from-source <REPO_PATH>	Dev mode: install operator-mcp from a local repo checkout instead of the embedded snapshot.

Under the hood, the installer detects Python 3, creates isolated per-sidecar virtual environments at ~/.revka/kumiho/venv/ and ~/.revka/operator_mcp/venv/, pip-installs kumiho[mcp]>=0.10.0 and kumiho_memory>=0.5.2 plus the Operator MCP package, writes the launcher scripts, and syncs Operator skills into ~/.revka/skills/. The Operator MCP source is embedded in the binary at compile time, so nothing is downloaded at runtime for it.

Sidecar	Launcher	Config key
Kumiho MCP	~/.revka/kumiho/run_kumiho_mcp.py	[kumiho].mcp_path
Operator MCP	~/.revka/operator_mcp/run_operator_mcp.py	[operator].mcp_path

Note

You rarely need to run this by hand. ensure_sidecars_ready runs transparently on every revka agent and revka daemon start; if the sidecars are missing, Revka prompts you interactively to install them. Updates preserve runtime state files (.json, .jsonl, .db, venv/, session-manager/, runlogs/).

Caution

--with-session-manager changes the auth and cost model. The Session Manager uses the Claude Agent SDK, which requires ANTHROPIC_API_KEY and bills pay-per-token. The default (Session Manager off) falls back to a subprocess path using claude --print + codex exec, which is OAuth-based and incurs no per-call API spend on spawned agents.

For the full sidecar walkthrough and verification commands, see Install the Python MCP sidecars and Kumiho setup.

revka update

revka update is Revka’s self-update command. It downloads the target release binary from GitHub Releases, verifies it, swaps it in, and rolls back automatically if anything fails.

revka update                  # download and install the latest release
revka update --check          # check for an update without installing
revka update --force          # install without the confirmation prompt
revka update --version 0.6.0  # install a specific release

Flag	Meaning
--check	Only check for updates; print current vs. latest version and exit.
--force	Skip the interactive confirmation prompt.
--version <X.Y.Z>	Target a specific release instead of the latest.

The 6-phase pipeline

The update runs as a fixed pipeline with automatic rollback on any failure:

1. Preflight — resolve the target version and confirm the binary is writable.
2. Download — fetch the release artifact for your platform.
3. Backup — copy the current binary aside so it can be restored.
4. Validate — sanity-check the download: minimum file size, that the binary’s CPU architecture (ELF/Mach-O header) matches the host, and that it runs --version and identifies as revka. (No SHA256 or signature verification is performed in revka update.)
5. Swap — replace the running binary with the new one.
6. Smoke test — run the new binary to confirm it executes; on failure, restore the backup.

Tip

If you installed Revka through a package manager, prefer that manager’s upgrade path instead of revka update — for example brew upgrade revka on macOS, or scoop update revka on Windows. See Updating, runbook & troubleshooting and macOS update & uninstall.

revka migrate

revka migrate imports memory and configuration from another agent runtime into Revka. OpenClaw is the only supported source in the current version.

revka migrate openclaw
revka migrate openclaw --source /custom/openclaw/workspace
revka migrate openclaw --dry-run

Flag	Meaning
--source <PATH>	OpenClaw workspace to import from. Default: ~/.openclaw/workspace.
--dry-run	Validate the source workspace and preview the migration without writing any data.

Always run --dry-run first to confirm the source is detected and to review what would be imported before committing.

revka desktop

revka desktop launches (or installs) the companion Tauri desktop app — a menu-bar / system-tray client that connects to your local gateway.

revka desktop             # launch the installed desktop app
revka desktop --install   # open the download page to install it

Flag	Meaning
--install	Open the download page; on macOS/Linux this launches the browser to https://www.kumiho.io/download.

Without --install, Revka searches for the desktop binary in order: /Applications/Revka.app (macOS), the directory of the CLI binary, ~/.cargo/bin/, ~/.local/bin/, then PATH. If none is found it exits with code 1. The app connects to the local gateway at http://127.0.0.1:42617/_app/, so the gateway must be running separately (revka gateway or revka daemon).

See the Desktop app page for the full feature tour.

revka plugin (feature-gated)

revka plugin manages WASM plugins. It is only present in binaries built with the plugins-wasm Cargo feature; standard builds do not expose this command.

revka plugin list
revka plugin install /path/to/plugin
revka plugin remove my-plugin
revka plugin info my-plugin

Subcommand	Argument	Meaning
list	—	List installed plugins.
install	<source>	Install from a local plugin directory (containing manifest.toml) or a local manifest path.
remove	<name>	Remove a plugin by name.
info	<name>	Show name, version, description, capabilities, permissions, and the WASM path.

For the plugin format and capability model, see WASM plugins and Cargo feature flags & ADRs.

revka completions

revka completions prints a shell completion script to stdout for the named shell. The output is stdout-only by design — no logging or config loading happens — so it is safe to source directly from a shell init file.

revka completions <shell>

The positional <shell> argument is required and must be one of: bash, fish, zsh, powershell, elvish.

Install per shell

# bash — source on the fly, or persist to your profile
source <(revka completions bash)
revka completions bash > ~/.local/share/bash-completion/completions/revka

# zsh — write to a directory on your $fpath
revka completions zsh > ~/.zfunc/_revka

# fish
revka completions fish > ~/.config/fish/completions/revka.fish

# PowerShell — append to your profile
revka completions powershell | Out-String | Invoke-Expression

# elvish
revka completions elvish >> ~/.config/elvish/rc.elv

revka acp

revka acp starts the ACP (Agent Control Protocol) server: a JSON-RPC 2.0 interface over stdin/stdout for IDE and tool integrations. It speaks the same agent loop as revka agent, exposed as multi-session RPC with streaming.

revka acp
revka acp --max-sessions 5
revka acp --session-timeout 7200

Flag	Default	Meaning
--max-sessions <N>	10	Maximum number of concurrent sessions.
--session-timeout <SECS>	3600	Session inactivity timeout, in seconds.

Protocol

ACP is JSON-RPC 2.0 framed over stdio. The supported methods are:

Method	Purpose
initialize	Handshake; negotiate capabilities.
session/new	Create a new agent session.
session/prompt	Send a prompt to a session.
session/stop	Terminate (remove) an agent session.

Agent reasoning, tool calls, and content are streamed back to the client as JSON-RPC notifications in real time. Because the transport is stdio, the host process (an IDE extension or editor) launches revka acp as a child process and communicates over its pipes — this is how Claude Code extensions and custom IDE integrations drive Revka.

Note

ACP runs the agent directly over stdio and does not require the gateway. If you instead want HTTP/WebSocket access to the same agent, run revka gateway and use the Gateway API.

See also

• revka onboard — initialize the workspace and config
• revka gateway, daemon & service — run the HTTP/WebSocket runtime
• revka doctor, status & self-test — verify an install end to end
• Revka as an MCP server — expose Revka’s tools to other MCP clients