Quick Start

Get SmartChats running on your machine in a few minutes.

Installation

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

The install command on a fresh Mac, up to where setup starts

The installer downloads a release for macOS (Apple Silicon) or Linux (x64 or arm64) into ~/.smartchats and then runs smartchats setup (shown under Quick start). The release bundles the CLI, the server, SurrealDB and the media storage (SeaweedFS). You don’t need Node, Bun or Docker.

Linux users. The installer needs tar and either curl or wget (preinstalled on most distros). If tar is missing: sudo apt install tar on Debian/Ubuntu, sudo dnf install tar on Fedora.

⚠️

Intel Macs. There is no binary release for Intel Macs, and the installer exits with a message. Use the npm package instead (see the Package Managers tab). It needs Node 24+.

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

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

If you see command not found, add the install directory to your PATH. The installer symlinks the CLI into /usr/local/bin when that directory is writable. Otherwise it adds ~/.smartchats/bin to ~/.zshrc, ~/.bashrc or your fish config.

export PATH="$HOME/.smartchats/bin:$PATH"

Installer flags go after bash -s --:

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

Flag	Default	Notes
`--version <tag>`	`latest`	Install a specific release tag
`--prefix <dir>`	`~/.smartchats`	Install location
`--non-interactive`	off	Don’t run `smartchats setup` after installing
`--no-path`	off	Don’t touch `/usr/local/bin` or shell rc files

iwr -useb https://smartchats.ai/install.ps1 | iex

⚠️

Windows support is experimental. The installer and the windows-x64 release exist, but they have not yet been tested on real Windows machines. Expect problems, and please report them on GitHub. If it doesn’t work for you, use WSL2 with the macOS & Linux install line.

The installer needs PowerShell 5 or later and Windows 10 1803 or later (for tar.exe). Only x64 is supported. Windows on ARM exits with an error because SurrealDB does not ship a Windows ARM build.

It installs to %USERPROFILE%\.smartchats, adds %USERPROFILE%\.smartchats\bin to your user PATH, and then runs smartchats setup.

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

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

To pass parameters, download the script first:

iwr -useb https://smartchats.ai/install.ps1 -o install.ps1
.\install.ps1 -Version v0.4.0 -NonInteractive

Parameter	Default	Notes
`-Version <tag>`	`latest`	Also read from `SMARTCHATS_VERSION`
`-Prefix <dir>`	`$HOME\.smartchats`	Also read from `SMARTCHATS_PREFIX`
`-NoPath`	off	Don’t change the user `PATH`
`-NonInteractive`	off	Don’t run `smartchats setup` after installing

If you have Node 24 or later:

npm install -g smartchats-ai

This installs the CLI only. It doesn’t include the Bun runtime or SurrealDB. smartchats setup checks for both and prints the install command for anything missing. It also needs git, because it clones the SmartChats source to ~/.smartchats/cli/source and builds it on first start.

Try without installing:

npx smartchats-ai setup

For most users the curl installer is simpler.

Each release publishes an all-in-one image (SurrealDB, media storage and the server) for linux/amd64 and linux/arm64:

docker pull sheunaluko/smartchats:latest   # or :v0.4.0

The same image is on GitHub’s registry as ghcr.io/sheunaluko/smartchats-aio.

To build it yourself instead, from a clone: docker build -f Dockerfile.aio -t smartchats-aio . (the build installs a published release, not your checkout. Pin one with --build-arg SMARTCHATS_VERSION=v0.4.0).

Put your keys in ~/.smartchats/.env, the same file a native install reads:

mkdir -p ~/.smartchats
cat > ~/.smartchats/.env <<EOF
TOGETHER_API_KEY=...          # default chat model + voice turn judge
AZURE_SPEECH_KEY=...          # default voice
AZURE_SPEECH_REGION=eastus
EOF
chmod 600 ~/.smartchats/.env

Then run the container:

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

Open http://localhost:3000. To the container your browser is another device, so the first visit asks you to pair: enter the code from docker logs smartchats (or run docker exec smartchats smartchats pair). You do this once per browser. Photos and files go through the same port to the media storage inside the container. The database and media live in the /data volume.

To check that it started, run:

docker logs smartchats
# Output: ... Stack up. Open: http://localhost:3000

⚠️

You need at least one LLM provider key. The container starts without one, but the agent cannot reply. docker logs smartchats shows a NO API KEYS CONFIGURED box when no key is found. See Required environment.

Ways to supply keys:

Method	When to use
`-v ~/.smartchats/.env:/root/.smartchats/.env:ro`	Same file as a native install. Edit it, then `docker restart smartchats`
`--env-file ~/.smartchats/.env`	Read once when the container is created
`-e OPENAI_API_KEY=$OPENAI_API_KEY`	One-off runs, CI

From a clone, bin/aio -d builds the image if it is missing and runs it the same way, forwarding provider keys from your shell.

For more, see Self-Hosting.

Upgrading

Once installed, smartchats can upgrade itself:

smartchats upgrade

This re-runs the installer in place. Your data directory, .env and config.json are kept. Restart the stack afterwards with smartchats restart.

Flag	Default	Notes
`--version <tag>`	`latest`	Install a specific release, for example `v0.4.0`
`-y, --yes`	off	Skip the confirmation prompt

npm users: run npm install -g smartchats-ai@latest instead. smartchats upgrade prints this and exits 1.

Source checkouts: run git pull in the repo.

Docker: docker pull sheunaluko/smartchats:latest (or rebuild with docker build --no-cache -f Dockerfile.aio -t smartchats-aio .), then remove and re-run the container. Data in the /data volume is kept.

Uninstalling

There is no uninstall command. To remove a curl install, stop the stack and delete the install directory:

smartchats stop
rm -rf ~/.smartchats
rm -f /usr/local/bin/smartchats

~/.smartchats holds your data (data/), keys (.env), config and logs. Export your data first if you want to keep it (see Backup + restore).

If the installer edited your shell rc file, delete the # Added by SmartChats installer line and the PATH line after it. If you signed in to the cloud, also delete ~/.smartchats-mcp/credentials.json.

Windows: delete %USERPROFILE%\.smartchats and remove %USERPROFILE%\.smartchats\bin from your user PATH.

npm: npm uninstall -g smartchats-ai. The clone at ~/.smartchats/cli/source stays until you delete it.

Docker: docker rm -f smartchats and docker rmi sheunaluko/smartchats:latest. Delete ~/.smartchats/data to remove your data too.

Quick start

After installing, run the guided setup (the installers run it for you):

smartchats setup

`smartchats setup` on a fresh install (the keys typed here are made up)

The wizard will:

Check your system. A binary install checks free disk only. A source or npm install also checks for bun and surreal.
Ask for each provider key in Providers & API Keys, starting with Together and Azure, the two the default setup uses (see Which keys matter). Press enter to skip any of them.
Write the .env file, start the stack and print http://localhost:3000. To use it from your phone, open the same address with your computer’s network name or IP and pair once with the code from smartchats pair.

# 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.

Which keys matter

setup and env ask for every key in Providers & API Keys, starting with the two the default setup uses: Together (the default chat model and the voice turn judge) and Azure Speech (the default voice). Every key is optional, but the agent needs at least one chat provider to reply.

Without Together, another provider’s model is used if it has a key, and the server skips the turn judge, so a pause mid-sentence ends the turn.
Without Azure, replies are spoken with an OpenAI voice if OpenAI has a key.
Without OpenAI, semantic search over your logs, knowledge graph and memory is off: OpenAI’s embeddings are currently the only ones SmartChats uses. Entries saved without a key are not embedded later, so add it early if you want them searchable.

To change keys later, run smartchats env, or edit ~/.smartchats/.env (<repo>/.env for a source install), then smartchats restart.

That’s it. Talk to the agent.

What’s next

CLI Reference: every command and flag.
Self-Hosting: env-var management, running on a VPS, Docker.
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