@kloom/app

Run Weave on your own machine — one command, no clone needed.

Quick Start

npx @kloom/app onboard

This will:

1. Check your environment (Node.js ≥ 20, Docker, and an AI runtime: claude, codex, or opencode)
2. Install the bundled Docker Compose stack to ~/.weave/self-hosted/
3. Generate secrets (ENCRYPTION_KEY, BETTER_AUTH_SECRET, INTERNAL_SHARED_SECRET)
4. Start all services with docker compose up -d (Postgres migrations run automatically)
5. Sign in as the bootstrap admin (username + password from the compose .env) and create your workspace
6. Register your AI runtime and start the daemon
7. Open the dashboard at http://localhost:15210

Commands

| Command | Description | | --- | --- | | npx @kloom/app onboard | Full setup: install, start, and register | | npx @kloom/app start | Start services from an existing installation | | npx @kloom/app stop | Stop the daemon and all services | | npx @kloom/app update | Pull the latest version, rebuild images, restart |

Embedded CLI

@kloom/app bundles a copy of @kloom/cli for managing the local daemon and runtime registration:

npx @kloom/app register          # Register this machine with the local server
npx @kloom/app daemon start      # Start the daemon
npx @kloom/app daemon stop       # Stop the daemon
npx @kloom/app daemon status     # Check daemon status
npx @kloom/app cli <any command> # Pass-through to @kloom/cli

Options

--port-web <port>   Web dashboard port (default: 15210)
--skip-register     Just install and start services; skip account creation

Architecture

@kloom/app is a thin launcher over a Docker Compose deployment (docker-compose.selfhost.yml). All services run as containers under the weave compose project:

| Service | Role | | --- | --- | | web | Next.js dashboard, REST API, auth (port WEB_PORT, default 15210) | | postgres | Primary database (Postgres + pgvector) | | redis | Cache and background job queue (BullMQ) | | seaweedfs | S3-compatible object storage | | centrifugo | Realtime updates over WebSocket | | mail + haraka | Outbound relay and inbound MX server | | jobs | Background worker (schedules, reminders, sweeps) | | mailpit | Dev-only local SMTP catcher for agent mail (UI at :8025) |

Only the web port is exposed by default; everything else talks over the internal compose network.

Files & state

~/.weave/self-hosted/
├── docker-compose.selfhost.yml   # the bundled stack
├── .env                          # auto-generated secrets + config (mode 0600)
└── (Docker named volumes hold Postgres / Redis / SeaweedFS data)

~/.weave/config.json              # CLI/daemon config: server URL, machine token

Configuration

onboard writes a working .env automatically. To customize a production deployment, edit ~/.weave/self-hosted/.env — see .env.selfhost.example for every option. The most important ones:

• WEAVE_DOMAIN — the domain your agents send/receive email on
• SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS — outbound relay for agent mail (replaces Mailpit for real email)
• ENCRYPTION_KEY, BETTER_AUTH_SECRET, INTERNAL_SHARED_SECRET — secrets

Variables use the WEAVE_ prefix; legacy ALOOK_ variables are still read for backward compatibility.

Dev Mode

With WEAVE_PROJECT_ROOT set, @kloom/app runs against the monorepo instead of the bundled stack (used by pnpm dev:app):

WEAVE_PROJECT_ROOT=/path/to/weave npx @kloom/app onboard

Requirements

• Node.js ≥ 20
• Docker (with docker compose)
• One of: claude, codex, or opencode CLI installed

License

Apache-2.0 — see LICENSE.