Self-Hosting

This page is for running SmartChats yourself: on your laptop, a VPS, a Raspberry Pi, anywhere with a shell.

For most people, Quick Start already covers it. This page goes further: env-var management, running on a VPS, Docker, and what runs inside the stack.

TL;DR

curl -fsSL https://smartchats.ai/install | bash
smartchats setup

That gives you a self-hosted SmartChats on your machine. Everything below is for cases where you need more control.

What you need

• macOS (Apple Silicon) or Linux with a shell. Intel Macs use the npm package. Windows is experimental (see Quick Start).
• An OpenAI API key. setup treats it as the required key. It covers chat models, embeddings and OpenAI voices.
• Optional: Anthropic, Google (Gemini), xAI, Together AI, Azure Speech and Serper keys for more models, the turn verdict, Azure voices and web search.
• 3 GB free disk. setup and doctor warn below that.

The installer bundles the CLI, the server (both compiled with Bun, runtime included) and the SurrealDB binary. No Node, no Docker, no system-level deps required.

The stack, briefly

smartchats start launches two processes:

                  ┌──────────────────────────────────────┐
                  │  smartchats-server  (port 3000)      │
                  │                                      │
                  │   • serves the SPA at /              │
                  │   • handles /local-api/* (health,    │
                  │     llm, tts, embeddings, data,      │
                  │     usage, keys, tools, insights,    │
                  │     storage)                         │
                  └─────────────────┬────────────────────┘
                                    │  ws://127.0.0.1:8000/rpc
                                    ▼
                  ┌──────────────────────────────────────┐
                  │  surreal  (port 8000, loopback only) │
                  │  ~/.smartchats/data/surreal.db       │
                  └──────────────────────────────────────┘
                          ▲
                          │
                   browser at :3000

The browser only needs port 3000. SurrealDB binds to 127.0.0.1. The server serves the static export of the Next.js app directly, so there is no Next.js runtime.

Where things live

smartchats home prints the install root (binary install) or the resolved source root.

Required environment

The stack boots without any keys, but the agent cannot reply until at least one LLM provider key is configured. smartchats start prints a NO API KEYS CONFIGURED box when it can’t find any.

Environment configuration

smartchats start reads the .env file at the install root (or repo root), merges in your shell environment, and passes the result to the server. A variable set in your shell wins over the same name in .env, so OPENAI_API_KEY=sk-... smartchats start overrides the file for one run.

Each provider has a SMARTCHATS_-prefixed name and one or more plain names. The server checks them in the order below and uses the first one set. If none is set, it falls back to a key stored in SurrealDB with POST /local-api/keys.

Azure Speech is read from the environment only. A database-stored Azure key is not used for voice.

Server settings

These are read by smartchats-server. smartchats start sets the SURREAL_*, SMARTCHATS_HOST, SMARTCHATS_PORT and SMARTCHATS_STATIC_DIR values itself, so setting them in .env has no effect under start. They matter when you run the server another way, such as smartchats dev.

Media storage. smartchats start runs SeaweedFS and sets these for the server, so you only set them to use your own S3-compatible bucket instead (all four are needed). See Storage for the bind address and the browser-facing endpoint:

Where the .env file lives

Ways to write keys:

smartchats env                   # interactive walkthrough (recommended)
smartchats env --list            # show what's configured (masked)
vi ~/.smartchats/.env            # direct edit, needed for xAI / Together / Azure

smartchats setup also writes the file on first run. After editing, run smartchats restart (or docker restart smartchats) to pick up the changes.

To check which keys the CLI sees, run:

smartchats env --list
# Output:
#   ✓ OpenAI                   sk-V…vGiE  (.env $OPENAI_API_KEY)
#   ✗ Anthropic (Claude)       not set  (optional)

Sharing one .env between bare-metal and Docker installs

The Docker container reads /root/.smartchats/.env (its install root), and the bare-metal install reads ~/.smartchats/.env on the host. Mounting the host file into the container reuses the same config:

docker run -d --name smartchats \
  -p 3000:3000 \
  -v ~/.smartchats/.env:/root/.smartchats/.env:ro \
  -v ~/.smartchats/data:/data \
  sheunaluko/smartchats:latest

Edit ~/.smartchats/.env later, then:

docker restart smartchats

Adding keys after the stack is running

• smartchats env on the host (recommended): interactive prompts, writes to ~/.smartchats/.env. Then smartchats restart, or docker restart smartchats if you mounted the file into the container.
• Edit the file directly: vi ~/.smartchats/.env, then restart. This is the only way to add xAI, Together and Azure keys.
• Store a key in SurrealDB with the keys API. No restart needed, and an environment key for the same provider still wins:

curl -X POST http://localhost:3000/local-api/keys \
  -H 'content-type: application/json' \
  -d '{"keys":{"together":"..."}}'

The API accepts openai, anthropic, google, xai, together and azure. GET /local-api/keys/providers shows which providers are available and where each key came from.

Other devices and scripts

The computer running SmartChats needs nothing. A phone or another computer pairs once: it shows Pair this device, and you enter the code from

smartchats pair
# Pairing code: 482 913   (valid 5 min, one device)

or from Settings → Devices → Pair a new device. smartchats devices lists paired devices and smartchats devices revoke <id> removes one.

In Docker your own browser is another device to the container, so it pairs once too. While nothing is paired, the container prints a code at startup (docker logs smartchats, valid 15 minutes); for a new one run docker exec smartchats smartchats pair.

Scripts and agents on other machines can send Authorization: Bearer $SMARTCHATS_API_KEY instead, when you set that variable. SMARTCHATS_AUTH=off turns all of this off. Details: Security.

Running on a VPS

The same install and commands work on a VPS. For a public deploy, put a reverse proxy in front for TLS and access control.

ssh user@vps
curl -fsSL https://smartchats.ai/install | bash

curl -fsSL https://smartchats.ai/install | bash -s -- --non-interactive
smartchats setup --no-prompt

# ufw example: allow SSH and HTTPS, deny direct access to 3000
sudo ufw allow OpenSSH
sudo ufw allow 443/tcp
sudo ufw deny 3000/tcp
sudo ufw enable

server {
  listen 443 ssl http2;
  server_name smartchats.your-domain.com;
 
  ssl_certificate     /etc/letsencrypt/live/.../fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/.../privkey.pem;
 
  auth_basic           "SmartChats";
  auth_basic_user_file /etc/nginx/.htpasswd;
 
  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    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;
  }
}

# /etc/systemd/system/smartchats.service
[Unit]
Description=SmartChats local stack
After=network.target
 
[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER
ExecStart=/home/YOUR_USER/.smartchats/bin/smartchats start --foreground --no-prompt
Restart=on-failure
RestartSec=5
 
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now smartchats
sudo systemctl status smartchats

#!/bin/bash
# /etc/cron.daily/smartchats-backup  (runs as root, so use full paths)
mkdir -p /home/YOUR_USER/backups
/home/YOUR_USER/.smartchats/bin/smartchats data export \
  /home/YOUR_USER/backups/$(date +%Y-%m-%d).json --target=local

Docker (alternative)

There is no published image. Build one from Dockerfile.aio in a clone of the repo:

git clone https://github.com/sheunaluko/smartchats.git
cd smartchats
docker build -f Dockerfile.aio -t smartchats-aio:latest .

Each release also publishes this image as sheunaluko/smartchats:<version> and :latest on Docker Hub, and as ghcr.io/sheunaluko/smartchats-aio on GitHub’s registry (linux/amd64 and linux/arm64), so building is optional. The Dockerfile runs curl … install | bash against debian:bookworm-slim, so the image contains a published release (pin one with --build-arg SMARTCHATS_VERSION=v0.4.0). Its entrypoint is smartchats start --data-dir=/data --foreground --no-prompt, and /data holds the database and media. Media storage runs inside the container and the browser reaches it through port 3000, so that is the only port to publish.

docker run -d --name smartchats \
  -p 3000:3000 \
  -v ~/.smartchats/.env:/root/.smartchats/.env:ro \
  -v ~/.smartchats/data:/data \
  sheunaluko/smartchats:latest

The .env mount is the same file the bare-metal CLI reads (~/.smartchats/.env), so one config works for both install modes. See Sharing one .env between bare-metal and Docker installs.

-e flags also work for one-off runs:

docker run --rm -p 3000:3000 \
  -e TOGETHER_API_KEY=$TOGETHER_API_KEY \
  -v ~/.smartchats/data:/data \
  sheunaluko/smartchats:latest

bin/aio in a clone wraps the build and run steps (--rebuild, -d, --port, --data-dir, --tag). It names the container smartchats, which is the name smartchats doctor checks.

Docker is useful when you need process isolation or container orchestration. For laptop self-hosting, the native install is simpler.

Backup + restore

# Snapshot (writes a single JSON file)
smartchats data export ~/snapshot.json --target=local
 
# Wipe and restore (the import upserts every row by id)
smartchats stop
rm -rf ~/.smartchats/data
smartchats start
smartchats data import ~/snapshot.json --target=local

The fresh stack boots with an empty database, and the import writes the rows back. data --target=local always connects to ws://localhost:8000/rpc, so it needs the default --surreal-port.

Troubleshooting

See also

• Quick Start: install and first run.
• CLI Reference: every command and flag.
• Architecture: the open / cloud boundary and what’s inside the stack.
• Contributing: modifying SmartChats itself.