For AI Agents

This page is for AI agents that install, configure or operate SmartChats on behalf of a user. Everything here runs without prompts and reports in machine-readable form. Plain-markdown copies of every docs page are at https://smartchats.ai/docs/<page>.md, indexed in /llms.txt and combined in /llms-full.txt. If you are working on the SmartChats code itself, read AGENTS.md in the repository instead.

What you are installing

A local stack of three processes, started and stopped together by the smartchats CLI:

The user talks to the agent in a browser at http://localhost:3000/app. The model provider keys are the user’s own.

Install without prompts

macOS (Apple Silicon) and Linux (x64, arm64):

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

This installs to ~/.smartchats and links smartchats into /usr/local/bin when it is writable (otherwise it adds ~/.smartchats/bin to the shell rc). Add --no-path to touch neither, then call ~/.smartchats/bin/smartchats directly. Add --version v0.4.0 to pin a release. Intel Macs have no binary release: use npm install -g smartchats-ai (Node 24+).

Docker, anywhere:

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

Configure keys

Keys live in ~/.smartchats/.env (mode 0600). Write them with the user’s consent and never echo them back. With the keys in the environment, setup --no-prompt saves them and starts the stack:

TOGETHER_API_KEY=... AZURE_SPEECH_KEY=... AZURE_SPEECH_REGION=eastus \
  smartchats setup --no-prompt

Or write the file and start:

umask 077
cat >> ~/.smartchats/.env <<'EOF'
TOGETHER_API_KEY=...
AZURE_SPEECH_KEY=...
AZURE_SPEECH_REGION=eastus
EOF
smartchats start --no-prompt

At least one chat provider key (Together, OpenAI, Anthropic, Google or xAI) is needed for the agent to reply. Restart after changing keys: smartchats restart. Every variable is listed in Providers & API Keys.

Verify

Each command exits 0 on success:

smartchats status --json
# {"up": true, "procs": [{"name": "surreal", "pid": 1234, "port": 8000, "pidAlive": true, "portHealthy": true, ...}, {"name": "seaweedfs", ...}, {"name": "server", ...}]}
 
smartchats doctor --json
# {"exit": 0, "results": [{"name": "LLM provider keys", "status": "pass", "severity": "warn", "note": "found: Together, Azure ..."}, ...], "port": 3000}
 
curl -s http://localhost:3000/local-api/health
# {"ok": true, "checks": {"data": {"ok": true, ...}, "providers": {"ok": true, ...}}}
 
curl -s http://localhost:3000/local-api/keys/providers
# {"llm": [{"provider": "together", "available": true, ...}, ...], "tts": [{"provider": "azure", "available": true, ...}, ...]}

From a clone of the repository, node scripts/smoke-stack.mjs http://localhost:3000 exercises the stack the way a user would: the app loads, a database query, an LLM reply, and a media upload and download. It prints one line per check and exits non-zero if any fails.

Operate

Process IDs and ports are in ~/.smartchats/run/pids.json. The database is in ~/.smartchats/data/surreal.db and media in ~/.smartchats/data/seaweedfs/.

When something is wrong

Give the user’s agent their data

SmartChats exposes the user’s data to other agents (Claude Desktop, Claude Code, Cursor and others) through an MCP server with tools to read and write logs, metrics, todos and the knowledge graph. See MCP Server.

Ground rules

• The data is the user’s: logs, journal entries and transcripts are personal. Don’t copy them anywhere the user didn’t ask for.
• Keys stay in ~/.smartchats/.env with mode 0600. Don’t print them, commit them, or pass them on the command line where other users can see them.
• The server listens on all interfaces. Other devices must pair, but don’t expose port 3000 to the internet without TLS and a reverse proxy that forwards Host and X-Forwarded-For (Security). Pair a device only when the user asks.

See also

• Quick Start
• Providers & API Keys
• Local Server
• CLI Reference