Skip to main content

​
Setup

If you are setting up for the first time, start with Getting Started. For onboarding details, see Onboarding (CLI).

​
TL;DR

  • Tailoring lives outside the repo: ~/.velaclaw/workspace (workspace) + ~/.Zavianx/velaclaw-dev.json (config).
  • Stable workflow: install the macOS app; let it run the bundled Gateway.
  • Bleeding edge workflow: run the Gateway yourself via pnpm gateway:watch, then let the macOS app attach in Local mode.

​
Prereqs (from source)

  • Node 24 recommended (Node 22 LTS, currently 22.14+, still supported)
  • pnpm preferred (or Bun if you intentionally use the Bun workflow)
  • Docker (optional; only for containerized setup/e2e — see Docker)

​
Tailoring strategy (so updates do not hurt)

If you want “100% tailored to me” and easy updates, keep your customization in:
  • Config: ~/.Zavianx/velaclaw-dev.json (JSON/JSON5-ish)
  • Workspace: ~/.velaclaw/workspace (skills, prompts, memories; make it a private git repo)
Bootstrap once:
From inside this repo, use the local CLI entry:
If you don’t have a global install yet, run it via pnpm velaclaw setup (or bun run velaclaw setup if you are using the Bun workflow).

​
Run the Gateway from this repo

After pnpm build, you can run the packaged CLI directly:

​
Stable workflow (macOS app first)

  1. Install + launch Velaclaw.app (menu bar).
  2. Complete the onboarding/permissions checklist (TCC prompts).
  3. Ensure Gateway is Local and running (the app manages it).
  4. Link surfaces (example: WhatsApp):
  1. Sanity check:
If onboarding is not available in your build:
  • Run velaclaw setup, then velaclaw channels login, then start the Gateway manually (velaclaw gateway).

​
Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.

​
0) (Optional) Run the macOS app from source too

If you also want the macOS app on the bleeding edge:

​
1) Start the dev Gateway

gateway:watch runs the gateway in watch mode and reloads on relevant source, config, and bundled-plugin metadata changes. If you are intentionally using the Bun workflow, the equivalent commands are:

​
2) Point the macOS app at your running Gateway

In Velaclaw.app:
  • Connection Mode: Local The app will attach to the running gateway on the configured port.

​
3) Verify

  • In-app Gateway status should read “Using existing gateway …”
  • Or via CLI:

​
Common footguns

  • Wrong port: Gateway WS defaults to ws://127.0.0.1:18789; keep app + CLI on the same port.
  • Where state lives:
    • Channel/provider state: ~/.velaclaw/credentials/
    • Model auth profiles: ~/.velaclaw/agents/<agentId>/agent/auth-profiles.json
    • Sessions: ~/.velaclaw/agents/<agentId>/sessions/
    • Logs: /tmp/velaclaw/

​
Credential storage map

Use this when debugging auth or deciding what to back up:
  • WhatsApp: ~/.velaclaw/credentials/whatsapp/<accountId>/creds.json
  • Telegram bot token: config/env or channels.telegram.tokenFile (regular file only; symlinks rejected)
  • Discord bot token: config/env or SecretRef (env/file/exec providers)
  • Slack tokens: config/env (channels.slack.*)
  • Pairing allowlists:
    • ~/.velaclaw/credentials/<channel>-allowFrom.json (default account)
    • ~/.velaclaw/credentials/<channel>-<accountId>-allowFrom.json (non-default accounts)
  • Model auth profiles: ~/.velaclaw/agents/<agentId>/agent/auth-profiles.json
  • File-backed secrets payload (optional): ~/.velaclaw/secrets.json
  • Legacy OAuth import: ~/.velaclaw/credentials/oauth.json More detail: Security.

​
Updating (without wrecking your setup)

  • Keep ~/.velaclaw/workspace and ~/.velaclaw/ as “your stuff”; don’t put personal prompts/config into the velaclaw repo.
  • Updating source: git pull + your chosen package-manager install step (pnpm install by default; bun install for Bun workflow) + keep using the matching gateway:watch command.

​
Linux (systemd user service)

Linux installs use a systemd user service. By default, systemd stops user services on logout/idle, which kills the Gateway. Onboarding attempts to enable lingering for you (may prompt for sudo). If it’s still off, run:
For always-on or multi-user servers, consider a system service instead of a user service (no lingering needed). See Gateway runbook for the systemd notes.