Skip to main content
GOWA Deployment And Access Overview GOWA ships as one binary. The REST API, webhooks, dashboard and MCP endpoint all start with whatsapp rest.

Requirements

Supported platforms: Linux (amd64, arm64, armv7, 386), macOS (Intel, Apple Silicon), Windows (amd64, 386; WSL recommended).

Docker

Images are published to Docker Hub and GHCR:
  • aldinokemal2104/go-whatsapp-web-multidevice
  • ghcr.io/aldinokemal/go-whatsapp-web-multidevice
  • /app/storages holds the SQLite databases (sessions, chat history, schedules, OAuth). Losing it unpairs every device.
  • /app/statics holds QR images, uploads and downloaded media.
  • The default command is rest. Pass flags after it, for example ... go-whatsapp-web-multidevice rest --autoreply="Away".
  • The entrypoint fixes volume ownership and drops privileges to gowauser (UID 20001, GID 20000).
  • Container time is UTC (TZ=UTC). Override TZ if you need local log timestamps.

Docker Compose

docker-compose.yml
Generate a stable webhook key with openssl rand -hex 32 and set WHATSAPP_WEBHOOK_SECRET in your shell or Compose .env before starting this example. The repository’s own docker-compose.yml builds the image from docker/golang.Dockerfile and reads src/.env. Use it when you want to build locally: cp src/.env.example src/.env && docker compose up -d --build.

Release binary

Download an archive from GitHub Releases. Archives are named whatsapp_<version>_<os>_<arch>.zip, for example:
Install the media tools on the host:
Verify the download against checksums.txt from the same release. ./whatsapp version prints the version; ./whatsapp --help lists every flag.

From source

On macOS also export CGO_CFLAGS_ALLOW="-Xpreprocessor" before building.

ARM without a C toolchain

The purego build tag selects a pure-Go SQLite driver, so you can cross-compile with CGO disabled:

Storage

By default everything is SQLite under storages/: DB_URI also accepts PostgreSQL, for example postgres://user:pass@host:5432/gowa?sslmode=verify-full. Remote PostgreSQL session stores default to certificate verification when no effective TLS mode is set. Explicit URI, environment, or PostgreSQL service TLS settings still apply. See storage configuration. GOWA creates SQLite files with owner-only 0600 permissions and new parent directories with 0700. Existing directories keep their permissions. Back up storages/ (or PostgreSQL plus storages/) to keep paired devices across rebuilds. Treat these backups as credentials.

Behind a reverse proxy

Serve GOWA under a subpath with APP_BASE_PATH, and trust the proxy’s forwarded headers with APP_TRUSTED_PROXIES:
/health stays at the root (/health, not /gowa/health) so probes work regardless of base path. The browser origin guard needs the public host. Preserve Host as above, or send X-Forwarded-Host from a trusted proxy. A separately hosted dashboard needs its exact origin in APP_TRUSTED_ORIGINS or APP_CORS_ALLOWED_ORIGINS. A wildcard does not authorize mutations or WebSockets. Serve the dashboard over HTTP or HTTPS, because file:// pages have an untrusted null origin. The default listener refuses to start without complete Basic Auth credentials. Only enable APP_ALLOW_UNAUTHENTICATED=true when the proxy authenticates callers and clients cannot bypass it. For local development without authentication, bind APP_HOST=127.0.0.1.

Verify

/health returns OK once storage is initialized. It does not report whether any WhatsApp account is connected; use GET /devices/{device_id}/status for that.

Upgrading

Back up storages/, pull the new image or binary, and restart. Read the release notes for breaking changes first. Notable ones: v6 made the rest subcommand mandatory, v7 moved binaries to GoReleaser archives, v8 added multi-device (device-scoped calls need X-Device-Id once more than one device exists), and the standalone whatsapp mcp mode (:8080/sse) was replaced by the /mcp endpoint on the REST server.