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-stoppedand 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/callbackwhen 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
| Docker | systemd | |
|---|---|---|
| Update | docker compose pull && docker compose up -d | sudo socialmate-update |
| Restart | docker compose restart | sudo systemctl restart socialmate |
| Logs | docker compose logs -f | journalctl -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.