Skip to content
SocialMate

The Claude Agent · Go live

Run it 24/7 on a server

The headless server with a browser admin.

Pro

The desktop app answers while your computer is on. For an agent that answers at 3 a.m., run SocialMate as a headless server on a Linux machine or VPS. It is the same backend from the same release — every agent feature, REST endpoint and webhook — and you manage it from the same screens in your browser at /admin.

Option A — Docker (recommended)

1Create docker-compose.yml

On the server, save this as docker-compose.yml. The image is built for amd64 and arm64.

services:
  socialmate:
    image: ghcr.io/micbwilliam/socialmate-server:latest
    container_name: socialmate
    restart: unless-stopped
    ports:
      - "3456:3456"
    environment:
      SOCIALMATE_ADMIN_PASSWORD: "${SOCIALMATE_ADMIN_PASSWORD:-}"
      SOCIALMATE_VAULT_KEY: "${SOCIALMATE_VAULT_KEY:-}"
      SOCIALMATE_API_HOST: "0.0.0.0"
    volumes:
      - sm-data:/data

volumes:
  sm-data:

2Set a vault key and a password, and start it

The vault key encrypts tokens at rest (a container has no OS keychain); generate it once and keep it stable.

export SOCIALMATE_VAULT_KEY=$(openssl rand -hex 32)
export SOCIALMATE_ADMIN_PASSWORD='choose-a-strong-one'
docker compose up -d
docker compose logs -f

Without SOCIALMATE_ADMIN_PASSWORD, a one-time password is printed to the logs on the first run. The password is read only on the first boot; change it later in the console under Settings → Server.

Behind a reverse proxy on the same server? Publish the port as "127.0.0.1:3456:3456" so only the proxy’s HTTPS faces the internet. Docker’s published ports bypass ufw, so a firewall rule alone does not close "3456:3456".

Option B — systemd (bare metal)

curl -fsSL https://github.com/micbwilliam/socialmate-releases/releases/latest/download/install.sh | sudo bash
journalctl -u socialmate -f

The installer runs the server on Node.js 22 — the system’s own when it is Node 22, otherwise a private copy under /opt/socialmate/node that leaves the system’s Node alone — and adds a socialmate system user, the server under /opt/socialmate, the data under /var/lib/socialmate (readable by that user only) and a service that starts on boot. It waits for the server to answer, then prints a generated admin password once and keeps it in /etc/socialmate/socialmate.env (root only).

HTTPS on your own domain: point its DNS at the server, open ports 80 and 443, and add -s -- --domain socialmate.example.com after sudo bash. Caddy fetches a Let’s Encrypt certificate, and the server is bound to 127.0.0.1, so port 3456 stops answering from outside. Usage analytics is on by default; add --no-telemetry to switch it off before the first start (or set SOCIALMATE_TELEMETRY=0, or DO_NOT_TRACK=1, in the env file — the Docker image reads the same variables).

Set up the agent in the browser

3Open the console

Go to http://<your-server>:3456/admin and sign in. Put TLS in front — a reverse proxy or the Pro named tunnel — before you expose the login to the internet.

4Link the number and create the agent

Everything from here is the same as on the desktop: Accounts → Add account shows the QR code in your browser, and Agents has the same wizard, Test tab and Inbox. Follow Your first agent in ten minutes.

What is different on a server

  • It keeps running. Docker’s restart: unless-stopped and the systemd service restart it after a crash and bring it back after a reboot. Reconnecting your numbers on start is a Pro feature, so on Pro the agent is answering again without you.
  • OAuth sign-ins for MCP servers come back to /admin/oauth/callback when the server has a public HTTPS tunnel; otherwise you paste the address your browser ended on (Add any MCP server).
  • Local MCP programs are off unless whoever runs the server sets SOCIALMATE_ALLOW_LOCAL_MCP=1.
  • Media library files (photos, documents, stickers) are added from the desktop app; in the browser console you can add saved locations and contact cards.
  • Voice replies arrive as real voice notes — the Docker image includes ffmpeg. On a systemd install with your own voice server, install ffmpeg too.
  • Ollama must be reachable from the server at the provider’s Endpoint URL. A slow local model can be given more time per turn with SOCIALMATE_AGENT_RUN_TIMEOUT_MS (up to 10 minutes).

Keep the data volume. One persisted volume is one stable machine id and one license seat. An ephemeral data folder looks like a new machine on every start and drops to Free. Two servers need two seats.

A VPS runs on a datacenter IP. On the desktop, SocialMate connects to WhatsApp from your home connection; a VPS cannot match that part, though the anti-ban pacing is identical. You can keep important numbers on the desktop at home, or route a server number through your own residential or mobile proxy (Pro, per number). It reduces a risk factor; no setup can promise WhatsApp won’t act on a number.

Updates

Dockersystemd
Updatedocker compose pull && docker compose up -dsudo socialmate-update
Restartdocker compose restartsudo systemctl restart socialmate
Logsdocker compose logs -fjournalctl -u socialmate -f

The console’s Settings → Updates tells you when a new release is out and gives you the command. Your numbers, agents and seat live in the data volume and survive updates; migrations run on start. Restarting is safe: linked numbers stay linked.

Logs also go to daily files in the data folder (.wa-agent-server/logs/sm-YYYY-MM-DD.log); SM_LOG_LEVEL (debug, info, warn, error) sets how much. Behind a proxy that is not on this machine or a private network, list it in SOCIALMATE_TRUST_PROXY so the login lockout sees real client addresses. A systemd install made on SocialMate 2.0 has an updater that cannot refresh itself: re-run the installer once (it keeps your data and password), then sudo socialmate-update works.

Prefer to start on the desktop? Get the app from the download page.

Put the Claude Agent on your WhatsApp number.

Download SocialMate, link your number, connect the model you want and create an agent from a preset. Start a free 7-day Pro trial from inside the app — test it on your real questions before a customer sees a word.

Pro: $99/year or $10/month. Built on Anthropic’s Claude Agent SDK — the model is your choice.

Free forever · no card Download free