Quickstart

This document is for readers deploying CollabVibe and running it end-to-end for the first time. The goal is to complete the shortest path to:

• install dependencies
• configure environment variables
• prepare the API backend command and workspace
• start the service
• validate the message and card path in Feishu

1. Prerequisites

Item	Description
Node.js	Required to run tsx, VitePress, and test scripts
npm / pnpm compatible environment	The current repository exposes scripts via npm run
Local filesystem	Stores data/, config, logs, SQLite, and workspace state
Feishu app credentials	Required for the current primary platform
Backend executable command	For example codex app-server

node -v
npm -v

2. Install dependencies

npm install

3. Prepare environment variables

Start from the existing environment template or your deployment environment variables. At minimum, prepare the following values:

Variable	Required	Purpose
FEISHU_APP_ID	Yes	Feishu app ID
FEISHU_APP_SECRET	Yes	Feishu app secret
FEISHU_SIGNING_SECRET	No	Event signature validation; usually optional in Stream mode
FEISHU_ENCRYPT_KEY	No	Encrypted-event support
CODEX_APP_SERVER_CMD	Recommended	Backend start command
COLLABVIBE_WORKSPACE_CWD	Recommended	Workspace root directory
CODEX_SANDBOX	No	Default sandbox policy
CODEX_APPROVAL_POLICY	No	Default approval policy
APPROVAL_TIMEOUT_MS	No	Approval timeout
COLLABVIBE_STREAM_PERSIST_WINDOW_MS	No	Streaming persist window for Path B
COLLABVIBE_STREAM_PERSIST_MAX_WAIT_MS	No	Streaming persist max wait
COLLABVIBE_STREAM_PERSIST_MAX_CHARS	No	Early persist flush threshold
COLLABVIBE_STREAM_UI_WINDOW_MS	No	Streaming UI flush window
COLLABVIBE_STREAM_UI_MAX_WAIT_MS	No	Streaming UI max wait
COLLABVIBE_STREAM_UI_MAX_CHARS	No	Early UI flush threshold
PORT	No	Service listening port
SYS_ADMIN_USER_IDS	Recommended	Initial system administrator IDs

cp .env.example .env

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
CODEX_APP_SERVER_CMD=codex app-server
COLLABVIBE_WORKSPACE_CWD=/abs/path/to/workspace
SYS_ADMIN_USER_IDS=ou_xxx
PORT=3100

These stream tuning variables are optional. In most deployments, keep the defaults unless you need to reduce burst frequency or improve perceived latency for high-volume turns.

4. Prepare local directories

Runtime depends on the following directories:

Path	Description
collabvibe.db	Main SQLite database
config/	Backend configuration directory
logs/	Runtime logs
COLLABVIBE_WORKSPACE_CWD	Root of the code workspace

mkdir -p config logs
mkdir -p /abs/path/to/workspace

5. Start the service

Development mode:

npm run start:dev

Production mode:

npm run start

Documentation preview:

npm run docs:dev

6. Complete the Feishu-side integration

Feishu is currently the primary platform for CollabVibe. On the first deployment, you need to complete bot creation, permission setup, event subscriptions, and visibility publishing on the platform side.

• See Feishu Integration for the platform steps
• If you just want to understand the current state, you can also review Slack Integration

7. Minimal validation

Validate in the following order:

1. The service starts without startup errors
2. The bot is visible in the target group chat or direct chat
3. Sending a user message triggers an event
4. The bot returns a message or card
5. logs/app.log contains the corresponding logs

tail -f logs/app.log

npm run test:workspace

8. Common commands

npm run start:dev
npm run start
npm run docs:dev
npm run docs:build
npm run test:workspace
npm test

9. Optional stream tuning

If your backend emits very dense streaming deltas, you can tune Path B throttling at the environment level:

COLLABVIBE_STREAM_PERSIST_WINDOW_MS=700
COLLABVIBE_STREAM_UI_WINDOW_MS=500
COLLABVIBE_STREAM_UI_MAX_WAIT_MS=1500

Use these only after you have validated the default behavior. Terminal events still force a final flush.

What to read next

• To understand the whole system: System Overview
• To understand the three core entities: Core Entities: Project / Thread / Turn