Quick Start

Get SmartChats running on your machine in under two minutes.

Installation

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

Linux users. The tar and unzip packages are required (preinstalled on most distros). If missing: sudo apt install tar unzip on Debian/Ubuntu, sudo dnf install tar unzip on Fedora. Kernel ≥ 3.10; check with uname -r.

To check that smartchats was installed successfully, open a new terminal window and run:

smartchats --version
# Output: 0.x.y

If you’ve installed smartchats but are seeing a command not found error, you may have to manually add the installation directory (~/.smartchats/bin) to your PATH.

Windows support is coming. For now, use WSL2 with the macOS/Linux install line above.

# In a WSL2 Ubuntu shell:
curl -fsSL https://smartchats.ai/install | bash

Native PowerShell installer is on the roadmap — track #W1 for progress.

If you already have Node 22+ installed and want a smaller install:

npm install -g smartchats-ai

This ships the CLI as a Node package (~few MB), but doesn’t bundle the Bun runtime or SurrealDB — smartchats setup will check for those and tell you what to install. For most users the curl | sh path above is friendlier.

Try without installing:

npx smartchats-ai setup

Homebrew formula and other package managers are tracked on the roadmap.

For containerized self-hosting:

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

This image is built by running the standard install script inside a fresh Debian — same code path as the bare-metal install, just wrapped for environments where you want process isolation. Open http://localhost:3000.

⚠️

You must provide at least an OpenAI API key. The container starts without one, but the agent cannot reply until at least one LLM provider key is configured. You’ll see a loud warning in docker logs smartchats-aio if you forget. See Required environment for the full list.

Three ways to supply keys — pick whichever fits your workflow:

Method	When to use
`-e OPENAI_API_KEY=$OPENAI_API_KEY` flag	One-off runs, CI
`--env-file ~/.smartchats/.env`	Multiple vars at once, file-based
`-v ~/.smartchats/.env:/root/.smartchats/.env:ro` (mounted)	Same file the bare-metal CLI uses — edit, then `docker restart` to pick up changes
Configure via the SPA’s Settings → BYO Keys page	No restart, stored in SurrealDB

The mounted-file pattern uses the same .env location convention as the bare-metal install (~/.smartchats/.env), so you can switch between Docker and native and keep one config file. Create it before starting the container:

mkdir -p ~/.smartchats
cat > ~/.smartchats/.env <<EOF
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
EOF
chmod 600 ~/.smartchats/.env
 
docker run --rm -p 3000:3000 \
  -v ~/.smartchats/.env:/root/.smartchats/.env:ro \
  -v ~/.smartchats/data:/data \
  smartchats/smartchats-aio:latest

For a full self-hosting walkthrough including env-var management, persistent volumes, and non-localhost bearer auth, see Self-Hosting.

Upgrading

Once installed, smartchats can upgrade itself:

smartchats upgrade

Re-runs the installer pinned to the latest release.

npm users: npm install -g smartchats-ai@latest instead.

Quick start

After installing, run the guided setup:

smartchats setup

`smartchats setup` — the install + first-run flow on macOS (Apple Silicon)

The wizard will:

Check your system (bun runtime, SurrealDB binary, disk space).
Collect your API keys for OpenAI (required), Anthropic, Google Gemini, Serper (all optional).
Build whatever the stack needs.
Start everything and open the app on http://localhost:3000.

# In a different terminal — check what's running:
smartchats status
 
# Stop the stack:
smartchats stop
 
# Tail logs:
smartchats logs -f
 
# Add or change provider API keys later (interactive):
smartchats env
# Then `smartchats restart` to pick up the changes.

That’s it. Talk to the agent.

What’s next

CLI Reference — every command and flag.
Self-Hosting — long-form guide: env-var management, BYO database, running on a VPS, bearer auth.
Architecture — how voice, agent runtime, knowledge graph, and sandboxed execution fit together.
MCP — expose smartchats to Claude Desktop and other MCP-aware tools.

Use the hosted SaaS instead

Don’t want to run infrastructure? Sign up at smartchats.ai — same stack, managed billing, no install. Free tier included.

Welcome Self-Hosting