本文へスキップ
Kurahi

Getting Started

このコンテンツはまだ日本語訳がありません。

Goal: go from zero → first working chat (with sane defaults) as quickly as possible.

Fastest chat: open the Control UI (no channel setup needed). Run kurahi dashboard and chat in the browser, or open http://127.0.0.1:18789/ on the gateway host. Docs: Dashboard and Control UI.

Recommended path: use the CLI onboarding wizard (kurahi onboard). It sets up:

  • model/auth (OAuth recommended)
  • gateway settings
  • channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/…)
  • pairing defaults (secure DMs)
  • workspace bootstrap + skills
  • optional background service

If you want the deeper reference pages, jump to: Wizard, Setup, Pairing, Security.

Sandboxing note: agents.defaults.sandbox.mode: "non-main" uses session.mainKey (default "main"), so group/channel sessions are sandboxed. If you want the main agent to always run on host, set an explicit per-agent override:

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.kolo/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) Prereqs

Section titled “0) Prereqs”
  • Node >=22
  • pnpm (optional; recommended if you build from source)
  • Recommended: Brave Search API key for web search. Easiest path: kurahi configure --section web (stores tools.web.search.apiKey). See Web tools.

macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough. Windows: use WSL2 (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See Windows (WSL2).

Section titled “1) Install the CLI (recommended)”
Terminal window
curl -fsSL https://kurahi.com/install.sh | bash

Installer options (install method, non-interactive, from GitHub): Install.

Windows (PowerShell):

Terminal window
iwr -useb https://kurahi.com/install.ps1 | iex

Install with the installers above or the offline bundle from GitHub Releases.

2) Run the onboarding wizard (and install the service)

Section titled “2) Run the onboarding wizard (and install the service)”
Terminal window
kurahi onboard --install-daemon

What you’ll choose:

  • Local vs Remote gateway
  • Auth: OAuth or API keys. Each provider supports the authentication methods listed on its provider page.
  • Providers: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
  • Daemon: background install (launchd/systemd; WSL2 uses systemd)
    • Runtime: Node.js 22.12 or newer (the installer bundle ships its own).
  • Gateway token: the wizard generates one by default (even on loopback) and stores it in gateway.auth.token.

Wizard doc: Wizard

Auth: where it lives (important)

Section titled “Auth: where it lives (important)”

  • API keys: the wizard can store a provider API key for service use. Each provider supports the authentication methods listed on its provider page.

  • OAuth credentials (legacy import): <KOLO_HOME>/credentials/oauth.json

  • Auth profiles (OAuth + API keys): ~/.kolo/agents/<agentId>/agent/auth-profiles.json

Headless/server tip: do OAuth on a normal machine first, then copy oauth.json to the gateway host.

3) Start the Gateway

Section titled “3) Start the Gateway”

If you installed the service during onboarding, the Gateway should already be running:

Terminal window
kurahi gateway status

Manual run (foreground):

Terminal window
kurahi gateway --port 18789 --verbose

Dashboard (local loopback): http://127.0.0.1:18789/ If a token is configured, paste it into the Control UI settings (stored as connect.params.auth.token).

3.5) Quick verify (2 min)

Section titled “3.5) Quick verify (2 min)”
Terminal window
kurahi status
kurahi health
kurahi security audit --deep

4) Pair + connect your first chat surface

Section titled “4) Pair + connect your first chat surface”

WhatsApp (QR login)

Section titled “WhatsApp (QR login)”
Terminal window
kurahi channels login

Scan via WhatsApp → Settings → Linked Devices.

WhatsApp doc: WhatsApp

Telegram / Discord / others

Section titled “Telegram / Discord / others”

The wizard can write tokens/config for you. If you prefer manual config, start with:

Telegram DM tip: your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.

5) DM safety (pairing approvals)

Section titled “5) DM safety (pairing approvals)”

Default posture: unknown DMs get a short code and messages are not processed until approved. If your first DM gets no reply, approve the pairing:

Terminal window
kurahi pairing list whatsapp
kurahi pairing approve whatsapp <code>

Pairing doc: Pairing

From source (development)

Section titled “From source (development)”

If you’re hacking on Kurahi itself, run from source:

Terminal window
git clone https://github.com/koda-tokyo/kurahi.git
cd kurahi
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
kurahi onboard --install-daemon

If you don’t have a global install yet, run the onboarding step via pnpm Kurahi ... from the repo. pnpm build also bundles A2UI assets; if you need to run just that step, use pnpm canvas:a2ui:bundle.

Gateway (from this repo):

Terminal window
node kolo.mjs gateway --port 18789 --verbose

7) Verify end-to-end

Section titled “7) Verify end-to-end”

In a new terminal, send a test message:

Terminal window
kurahi message send --target +15555550123 --message "Hello from Kurahi"

If kurahi health shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.

Tip: kurahi status --all is the best pasteable, read-only debug report. Health probes: kurahi health (or kurahi status --deep) asks the running gateway for a health snapshot.

Next steps (optional, but great)

Section titled “Next steps (optional, but great)”