Quickstart

This page takes you from a fresh install to a running gateway, the web dashboard, and your first agent reply — all from the revka CLI. Use it right after installing Revka when you want the shortest path to a working agent. For a guided, step-by-step setup of providers, channels, memory, and tunnels, run the onboarding wizard instead.

Note

Every command below works offline except those that call your LLM provider or a running gateway. You only need network access for the agent reply in steps 2 and 4.

Prerequisites

• The revka binary on your PATH. If you haven’t installed it yet, see Installation.
• An API key for an LLM provider (OpenRouter is the default; Anthropic, OpenAI, Ollama, and many others are supported).

Verify the binary is reachable:

revka --version

1. Initialize your config

Run the onboarding setup once to create your workspace and write ~/.revka/config.toml. The fastest path is the scriptable quick setup:

revka onboard --api-key "sk-..." --provider openrouter

This writes a default config (provider openrouter, memory sqlite, temperature 0.7) and a workspace under ~/.revka/workspace/. To pick a different provider, model, or memory backend:

revka onboard --api-key "sk-..." --provider anthropic --model claude-sonnet-4-20250514 --memory kumiho

Run revka onboard with no flags in a terminal to get the interactive wizard instead. See Onboarding wizard for the full flow.

Tip

You can skip writing the key to disk by setting it in the environment instead — REVKA_API_KEY, REVKA_PROVIDER, and REVKA_MODEL all override the config file at runtime.

2. Send your first agent message

Before standing up the gateway, confirm your provider key works with a single-shot agent query. The -m flag runs one message and exits — no interactive loop, no gateway required:

revka agent -m "In one sentence, what is Revka?"

Useful flags for revka agent:

Flag	Meaning
-m, --message <TEXT>	Single-message mode (no interactive loop)
-p, --provider <ID>	Override the configured default provider
--model <MODEL_ID>	Override the configured default model
-t, --temperature <0.0-2.0>	Override the configured temperature
--session-state-file <PATH>	Persist and restore session state across runs

If you get a reply, your provider and key are working. To drop into a back-and-forth session instead, run revka agent with no flags. See revka agent for the full reference.

3. Start the gateway

The gateway hosts the REST API, WebSocket and SSE endpoints, and the embedded React dashboard. Start it in the foreground:

revka gateway

By default the gateway binds to 127.0.0.1 and prints its URL on startup. The listen port comes from your config ([gateway].port); a fresh quick-setup writes 8080, while the built-in schema default is 42617. Common variations:

revka gateway start -p 8080          # explicit port
revka gateway start -p 0             # pick a random available port
revka gateway restart                # graceful restart

Caution

Binding to a non-loopback address such as 0.0.0.0 is refused unless you set allow_public_bind = true under [gateway] (or REVKA_ALLOW_PUBLIC_BIND=true). To reach the gateway from the public internet, keep it on localhost and front it with a tunnel — see Expose your gateway with a tunnel.

For a long-running setup that also starts channels, the heartbeat, and the cron scheduler, use revka daemon or register it as an OS service with revka service install.

4. Open the dashboard

With the gateway running, open the dashboard in your browser at the printed URL — the root path serves the React app:

http://127.0.0.1:8080/

Revka ships with require_pairing = true by default, so the first connection needs a one-time pairing code before it can mint a bearer token. Show (or rotate) the current code from the CLI:

revka gateway get-paircode          # show current pairing code
revka gateway get-paircode --new    # rotate to a fresh code

Enter that code when the dashboard prompts you, and it will exchange it for a bearer token scoped to your browser. To pair a non-browser client (for example, a phone or a script), exchange the code for a token directly:

revka pair token --code 123456 --name "My laptop"

Caution

The plaintext bearer token is printed exactly once — Revka stores only a hash. Save it immediately if you need it for API calls.

Once paired, the dashboard gives you chat, workflows, the memory graph, approvals, and audit views. See Dashboard overview and Run the dashboard for a tour.

5. Smoke-test with the CLI channel

The CLI channel is the simplest way to chat with your agent end-to-end — it runs over your terminal’s stdin/stdout with zero external credentials, so it’s the ideal smoke test before wiring up Telegram, Discord, or any remote channel. Enable it in ~/.revka/config.toml:

[channels_config]
cli = true

Then start an interactive chat:

revka chat

Type a message, read the reply, and exit with /quit or /exit. If you get a coherent answer here, your provider, memory backend, and agent loop are all wired correctly. From here, connect a real messaging platform with Connect a messaging channel.

6. Confirm everything is healthy

Print a full system summary — version, workspace, provider/model, memory backend, security, and channels:

revka status

For a machine-readable liveness probe (used by Docker’s healthcheck), check the exit code instead:

revka status --format exit-code     # exits 0 if the gateway is healthy, 1 otherwise

If anything looks off, run the structured diagnostics:

revka doctor          # config, workspace, daemon, environment, sidecars, kumiho, cli-tools
revka self-test       # full suite, including a gateway health + memory round-trip

See Diagnostics for how to read the reports.

Next steps

Onboarding wizard Walk through providers, channels, memory, and tunnels interactively.

Chat with your agent Deeper guide to interactive sessions, sessions, and model routing.

Connect a messaging channel Move from the CLI smoke test to Telegram, Discord, Slack, and more.

Run as a background service Keep the daemon running with systemd, launchd, or Windows Task Scheduler.