Installation

Install GOWA with Docker, Docker Compose, a release binary or from source, and run it behind a reverse proxy.

GOWA ships as one binary. The REST API, webhooks, dashboard and MCP endpoint all start with whatsapp rest.

Requirements

Item	Needed for
FFmpeg	Media conversion (video, voice notes). Included in the Docker image.
libwebp tools (cwebp, dwebp, webpmux)	Stickers, including animated WebP. Included in the Docker image.
Go 1.26+	Building from source only.

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

docker volume create gowa_storages
docker volume create gowa_statics

docker run -d --name gowa --restart always \
  -p 3000:3000 \
  -v gowa_storages:/app/storages \
  -v gowa_statics:/app/statics \
  -e APP_BASIC_AUTH=admin:changeme \
  aldinokemal2104/go-whatsapp-web-multidevice:latest

• /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

services:
  gowa:
    image: aldinokemal2104/go-whatsapp-web-multidevice:latest
    container_name: gowa
    restart: always
    ports:
      - "3000:3000"
    environment:
      APP_BASIC_AUTH: admin:changeme
      WHATSAPP_WEBHOOK: https://example.com/wa-hook
      WHATSAPP_WEBHOOK_SECRET: change-me
    volumes:
      - gowa_storages:/app/storages
      - gowa_statics:/app/statics

volumes:
  gowa_storages:
  gowa_statics:

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:

curl -LO https://github.com/aldinokemal/go-whatsapp-web-multidevice/releases/download/v9.7.0/whatsapp_9.7.0_linux_amd64.zip
unzip whatsapp_9.7.0_linux_amd64.zip
chmod +x whatsapp
./whatsapp rest

Install the media tools on the host:

# Debian/Ubuntu
sudo apt install ffmpeg webp
# macOS
brew install ffmpeg webp

Verify the download against checksums.txt from the same release. ./whatsapp version prints the version; ./whatsapp --help lists every flag.

From source

git clone https://github.com/aldinokemal/go-whatsapp-web-multidevice.git
cd go-whatsapp-web-multidevice/src
cp .env.example .env    # optional
go build -o whatsapp
./whatsapp rest

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:

# Raspberry Pi 2/3/4 (ARMv7)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -tags purego -o whatsapp-armv7
# Raspberry Pi Zero/1 (ARMv6)
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -tags purego -o whatsapp-armv6

Storage

By default everything is SQLite under storages/:

Data	Default	Setting
WhatsApp sessions and keys	file:storages/whatsapp.db	DB_URI
Session key cache (optional, separate DB)	uses DB_URI	DB_KEYS_URI
Chat history, device registry, schedules	file:storages/chatstorage.db	not configurable
MCP OAuth clients and tokens	file:storages/oauth.db	MCP_OAUTH_DB_URI

DB_URI also accepts PostgreSQL, for example postgres://user:pass@host:5432/gowa?sslmode=disable. Back up storages/ (or the PostgreSQL database plus storages/) to keep paired devices across rebuilds.

Behind a reverse proxy

Serve GOWA under a subpath with APP_BASE_PATH, and trust the proxy’s forwarded headers with APP_TRUSTED_PROXIES:

./whatsapp rest --base-path=/gowa --trusted-proxies=10.0.0.0/8

location /gowa/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;     # WebSocket at /gowa/ws
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    client_max_body_size 100m;                  # largest upload GOWA accepts
}

/health stays at the root (/health, not /gowa/health) so probes work regardless of base path.

Verify

curl http://localhost:3000/health                      # OK, no auth needed
curl -u admin:changeme http://localhost:3000/app/info  # server info, no device needed
curl -u admin:changeme http://localhost:3000/devices   # registered devices

/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.