Quick Start

Choose the runtime host first

aibuddy provides two development paths. Web is for hosted, multi-user, and background execution. Desktop is for local data, local files, and shell execution. Both use the task semantics and agent behavior in @aibuddy/core; you do not need to start both.

One task model, two runtime hosts Platform capabilities adapt independently; the shared runtime defines agent behavior Web host ENTRY Browser EXECUTION Server Worker STORAGE PostgreSQL Redis Desktop host ENTRY Renderer EXECUTION Electron Main STORAGE SQLite Local FS Platform adapter boundary Shared Task and Agent Runtime context · tools · memory · state · cancellation · finalization Both hosts preserve the same task semantics and completion criteria First-run verification ① Reply streams ② Tools are visible ③ Task converges

What you want to verifyChooseRuntime composition
Web UI, API, queues, or multi-user behaviorWebBrowser, Hono Server, PostgreSQL, and optionally Redis/BullMQ
Electron, local data, or host executionDesktopRenderer, Electron Main, SQLite, and the local Node sandbox

This page is not a production deployment. Its goal is one completed task whose reply, tool activity, and terminal state are all observable. Cross-instance recovery and remote sandboxes are outside the first-run path.

Both paths share the same base setup

The repository requires Node.js >=24 <25 and pins pnpm 11.14.0 through Corepack. Web additionally requires PostgreSQL 15 or later. Redis is needed only when exercising BullMQ, schedules, cross-instance events, or resumable streams.

git clone https://github.com/lib4x/aibuddy.git
cd aibuddy
corepack enable
corepack prepare [email protected] --activate
pnpm install

After installation, follow one platform path below.

Web runs the first task with the minimum service set

Copy the Server configuration:

cp apps/server/.env.example apps/server/.env

A first local run needs a database, an authentication secret, and a working model endpoint. This configuration uses the inline queue, so Redis is not required yet:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aibuddy
BETTER_AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
BASE_URL=http://localhost:8001
AI_GATEWAY_API_KEY=your-ai-gateway-key
SANDBOX_TYPE=node
JOB_QUEUE_MODE=inline

Create the database, initialize its schema and seed data, then start the Web, API, and worker processes:

createdb aibuddy
pnpm --filter=@aibuddy/server db:setup
pnpm dev:app

Open http://localhost:8000. Register a user, or sign in with the seeded account [email protected] / admin@123. Create a Task and ask the agent to read or create a small file so the run exercises both message streaming and tool execution.

JOB_QUEUE_MODE=inline is only the minimum development path. Configure REDIS_URL and use BullMQ when validating queue retries, schedules, cross-instance delivery, or resumable streams.

Desktop runs the same task model locally

Copy the Desktop configuration and start the app:

cp apps/desktop/.env.example apps/desktop/.env
pnpm dev:desktop

In development, ELECTRON_RENDERER_URL should point to http://localhost:8002. Complete first-run setup in this order:

  1. Add and validate a provider key under Settings → API Keys.
  2. Add at least one model for that provider.
  3. Create a Task and ask the agent to read or create a small file.

Desktop executes the agent turn inline in Electron Main. It does not require Server, PostgreSQL, Redis, or BullMQ. Local SQLite stores tasks, conversations, and model configuration; Electron safeStorage protects provider credentials.

Three signals establish a successful run

Do not treat one visible reply as sufficient evidence. A first run should satisfy all three conditions:

  1. The reply streams: the UI receives incremental text rather than one stateless response.
  2. Tool activity is inspectable: when the task requires a tool, the UI shows the call and its result.
  3. The task converges to an explicit state: the Task ends as completed, waiting, cancelled, or failed instead of remaining indefinitely active.

A plain question is enough to test model connectivity. To test the full task path, ask the agent to operate on a disposable file and verify that the file contents agree with the final reply.

Diagnose failures at the boundary where they occur

SymptomCheck first
Web loads, but API requests return 404Whether apps/server is running at localhost:8001
Web sign-in fails or redirects repeatedlyBASE_URL and the authentication secret
Web reports a database error during startupPostgreSQL, DATABASE_URL, and db:setup
The first message returns model authentication errorsThe Gateway or provider key and the selected model
Desktop remains in first-run setupA validated API key and at least one user model
Desktop opens a blank windowWhether ELECTRON_RENDERER_URL points to localhost:8002
The agent replies but tools are unavailableSANDBOX_TYPE, the task workspace, and the relevant process log
A Task remains active indefinitelyServer/Worker or Electron Main logs

A successful first run does not imply platform parity

Web and Desktop share the task model, not every infrastructure capability. Web multi-user identity, BullMQ, cross-instance events, and object storage depend on server configuration. Desktop uses device-local identity, storage, and execution. Its MCP provider is not wired yet. The Node sandbox also runs in the host process tree and is not equivalent to a remote isolation boundary.

These differences do not change the basic semantics of Tasks, context, tool events, and terminal states. They do change where data lives, which capabilities are available, and how far recovery can go.

  • System overview — move from the first run to the complete system model.
  • Task runtime — how Tasks, event streams, cancellation, and recovery form one runtime.
  • Product and platforms — what Web and Desktop share and which responsibilities remain host-specific.
  • Repository architecture — package boundaries and dependency structure for contributors.
Was this page helpful?
Edit on GitHub