Run WATeamInbox on your own server.

The root development compose file provides PostgreSQL, NATS, Centrifugo, Meilisearch, and MinIO. The root bun run dev command starts the application processes: the web app, the API, and the Go workers.

Quick start

git clone https://github.com/ygncode/wateaminbox.git
cd wateaminbox

# Create the ignored local environment file.
cp .env.example .env

# Install JavaScript dependencies and fetch Go dependencies during builds.
bun install

# Start PostgreSQL, NATS, Centrifugo, Meilisearch, and MinIO.
docker compose up -d

# Create the central and tenant database structures.
bun run db:migrate

# Start the web app, API, and Go workers.
bun run dev

Open the web app at http://localhost:4444. The API is at http://localhost:4445/api.

Local service map

NATS monitoring is available at http://localhost:8222. The optional NATS toolbox can be started with docker compose --profile debug up -d nats-box.

The checked-in root .env.example is the authoritative development inventory. Copy it, then change the secrets and any hostnames that differ from the defaults. Environment variables are loaded from the repository root when commands run from the root.

Browser URLs

The web client defaults to the local API URL. Set these values when the browser reaches the API or Centrifugo through a different host, port, or TLS endpoint:

VITE_API_URL=http://localhost:4445/api
VITE_CENTRIFUGO_URL=ws://localhost:4451/connection/websocket

The website and managed Cloud service

The public marketing site and the commercial Cloud control plane are maintained outside this open-source project. Self-hosted deployments do not need either repository and should configure their own application, API, realtime, storage, and email origins.

The public website links to https://app.wateaminbox.com for the managed service. That hosted environment has its own billing and entitlement controls; none of its commercial configuration belongs in the MIT-licensed repository.

1. 1
   Create and verify your user.

   Open the web app at your configured APP_URL, register, and verify the email link. Create a workspace or accept an invitation.

2. 2
   Open Settings → Connections.

   Add a named WhatsApp connection. The default maximum is five active or pending connections; a company-level setting can change that limit.

3. 3
   Scan the pairing QR code.

   On the phone, open WhatsApp → Settings → Linked Devices → Link a Device, then scan the code shown by the workspace. The code expires quickly; restart the pairing attempt if the UI reports expiry.

4. 4
   Watch the initial history sync.

   Messages, contacts, groups, receipts, and available media are imported through the worker and API. The UI exposes sync progress; a connected account may continue processing history after pairing.

Access is workspace-scoped. Roles provide defaults, while the owner can apply custom permissions to admins and members. Conversation visibility is not automatically global: without can_view_all_chats, a member normally sees active assignments.

These are the main surfaces represented by the current web, API, database, and worker code. Feature access still depends on role, connection state, migrations, and configuration.

Do not promote the development docker-compose.yml to production. The repository’s compose.production.yml is a single-host baseline with Caddy at the edge, an internal readiness-aware HAProxy router, and private data services. It can run 1–10 homogeneous API replicas while keeping the orchestrator as a singleton. Multiple API processes improve process and release resilience, not host availability. This is deployment guidance, not a hosted service or a guarantee of production readiness for every environment.

The API base is /api in the documented reverse-proxy shape, or http://localhost:4445/api locally. Most workspace routes require a short-lived bearer access token and the X-Company-ID header. Refresh tokens are held in an HttpOnly cookie; do not copy server secrets into browser variables.

Authorization: Bearer <access-token>
X-Company-ID: <workspace-uuid>

The canonical send route is POST /api/messages. POST /api/conversations/:id/messages remains for compatibility and is deprecated. Export routes return CSV, JSON, or ZIP rather than only JSON. See the route source ↗ for the current surface.

Realtime transport

The browser obtains a short-lived token from POST /api/realtime/token and connects to the configured Centrifugo WebSocket endpoint. Events invalidate or update local UI state; clients reconcile with PostgreSQL-backed API reads after reconnects.

message:new
message:status
contact:updated
connection:status
notification:new
labels:updated
catalogs:updated