---
summary: "Advanced setup and development workflows for KaijiBot"
read_when:
  - Setting up a new machine
  - You want “latest + greatest” without breaking your personal setup
title: "Setup"
---

# Setup

<Note>
If you are setting up for the first time, start with [Getting Started](/start/getting-started).
For onboarding details, see [Onboarding (CLI)](/start/wizard).
</Note>

## TL;DR

- **Tailoring lives outside the repo:** `~/.kaijibot/workspace` (workspace) + `~/.kaijibot/kaijibot.json` (config).
- **Standard workflow:** run `kaijibot setup`, configure Feishu credentials, then start the Gateway.
- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch` for hot-reload development.

## 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](/install/bun))
- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))

## Tailoring strategy (so updates do not hurt)

If you want “100% tailored to me” _and_ easy updates, keep your customization in:

- **Config:** `~/.kaijibot/kaijibot.json` (JSON/JSON5-ish)
- **Workspace:** `~/.kaijibot/workspace` (skills, prompts, memories; make it a private git repo)

Bootstrap once:

```bash
kaijibot setup
```

From inside this repo, use the local CLI entry:

```bash
kaijibot setup
```

If you don’t have a global install yet, run it via `pnpm kaijibot setup` (or `bun run kaijibot setup` if you are using the Bun workflow).

## Run the Gateway from this repo

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

```bash
node kaijibot.mjs gateway --port 18789 --verbose
```

## Standard workflow (Feishu channel)

1. Run setup:

```bash
kaijibot setup
```

2. Configure Feishu credentials:

```bash
kaijibot config set channels.feishu.appId "your-app-id"
kaijibot config set channels.feishu.appSecret "your-app-secret"
```

Create your Feishu app at [open.feishu.cn](https://open.feishu.cn/) and enable
WebSocket events.

3. Start the Gateway:

```bash
kaijibot gateway
```

4. Sanity check:

```bash
kaijibot health
```

If onboarding is not available in your build:

- Run `kaijibot setup`, then `kaijibot gateway` manually.

## Bleeding edge workflow (Gateway in a terminal)

Goal: work on the TypeScript Gateway, get hot reload.

### 1) Start the dev Gateway

```bash
pnpm install
pnpm gateway:watch
```

`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:

```bash
bun install
bun run gateway:watch
```

### 2) Verify

```bash
kaijibot health
```

### 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: `~/.kaijibot/credentials/`
  - Model auth profiles: `~/.kaijibot/agents/<agentId>/agent/auth-profiles.json`
  - Sessions: `~/.kaijibot/agents/<agentId>/sessions/`
  - Logs: `/tmp/kaijibot/`

## Credential storage map

Use this when debugging auth or deciding what to back up:

- **Feishu credentials**: `channels.feishu.appId` and `channels.feishu.appSecret` in config or env
- **Pairing allowlists**:
  - `~/.kaijibot/credentials/<channel>-allowFrom.json` (default account)
  - `~/.kaijibot/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
- **Model auth profiles**: `~/.kaijibot/agents/<agentId>/agent/auth-profiles.json`
- **File-backed secrets payload (optional)**: `~/.kaijibot/secrets.json`
- **Legacy OAuth import**: `~/.kaijibot/credentials/oauth.json`
  More detail: [Security](/gateway/security#credential-storage-map).

## Updating (without wrecking your setup)

- Keep `~/.kaijibot/workspace` and `~/.kaijibot/` as “your stuff”; don’t put personal prompts/config into the `kaijibot` 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:

```bash
sudo loginctl enable-linger $USER
```

For always-on or multi-user servers, consider a **system** service instead of a
user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.

## Related docs

- [Gateway runbook](/gateway) (flags, supervision, ports)
- [Gateway configuration](/gateway/configuration) (config schema + examples)
- [Feishu](/channels/feishu) (App ID, App Secret, WebSocket event setup)
- [KaijiBot assistant setup](/start/kaijibot)
