README
¶
chatz
Self-hosted AI chat with OpenAI-compatible and Anthropic models, MCP tools, and an embedded web app. Run one Docker image with SQLite, or use Postgres when needed.
Features
- Streaming conversations. Messages, reasoning, and tool calls arrive as the model produces them. Stop or refresh without losing the submitted prompt.
- Models you already use. Connect OpenAI-compatible or Anthropic endpoints. Chatz discovers their models and keeps provider-specific settings in the chat.
- MCP tools. Admins add stdio or HTTP MCP servers, then users enable their tools per chat. Stored MCP credentials are encrypted and stay masked in the admin UI.
- Useful chat controls. Set temperature, reasoning, output size, and the history budget per chat. Create, rename, search, archive, and pin chats.
- Generative UI. Model and tool output can render tables, status panels, charts, log viewers, and other live components in the conversation. See the rendering guide for the component catalog.
- Admin-managed access. The first user is the admin. That admin creates the other accounts and configures upstreams and MCP servers.
- Demo mode. Set
CHATZ_SHOWCASE_MODE=trueto return fixed streamed replies for exact demo prompts. Normal chats keep using the selected model.
Quickstart
Chatz ships as the psyb0t/chatz Docker image. The fastest path uses SQLite in
a persistent Docker volume. It needs no LLM configuration for the first run.
docker pull psyb0t/chatz:latest
docker volume create chatz-data
touch chatz.log
sudo chown 1000:1000 chatz.log
docker run --name chatz --detach --restart unless-stopped --init \
--publish 127.0.0.1:8080:8080 \
--env CHATZ_DB_DRIVER=sqlite \
--read-only \
--tmpfs /tmp:rw,noexec,nosuid,size=64m \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--memory 512m \
--cpus 1.0 \
--pids-limit 256 \
--mount type=bind,src="$(pwd)/chatz.log",dst=/app/chatz.log \
--volume chatz-data:/data \
psyb0t/chatz:latest run
Open http://localhost:8080, then visit /setup to create the admin.
The chat works before you configure an LLM, but the model picker stays empty.
latest is for a first look. Pin an immutable release tag such as
psyb0t/chatz:v0.7.7 for deployment. Copy .env.example to .env, set
CHATZ_DB_DRIVER=sqlite, and add --env-file .env to configure upstreams,
MCP secret storage, or other settings. Chatz exposes GET /healthz.
Try fixed demo replies
Start the normal stack with fixed-response mode:
CHATZ_SHOWCASE_MODE=true docker compose up --build
After completing /setup, select a configured model and send one of these
exact prompts:
Show me what's happening across the production platform right now.Where are we losing deals in the sales pipeline?Which customers are at risk and who should the team contact first?
Each returns a paced reply with thinking, tool calls, and a dashboard. Any other message uses the selected model and normal MCP-enabled chat path.
Connect a model
Copy .env.example to .env and set CHATZ_UPSTREAMS. Each upstream chooses
the openai driver, which also works with OpenAI-compatible APIs, or the
anthropic driver. apiKeyEnv names a variable in .env; never put the key
in the JSON.
[
{"name":"openai","provider":"openai","baseUrl":"https://api.openai.com/v1","apiKeyEnv":"OPENAI_API_KEY"},
{"name":"anthropic","provider":"anthropic","apiKeyEnv":"ANTHROPIC_API_KEY"},
{"name":"ollama","provider":"openai","baseUrl":"http://localhost:11434/v1"}
]
Docker Compose loads .env automatically. Add --env-file .env to the Docker
command above. The example environment file documents model
metadata, timeouts, and every other setting.
Generate a 32-byte base64 key before adding MCP credentials, then set it as
CHATZ_SECRETS_KEY:
openssl rand -base64 32
Without this key, Chatz refuses to store MCP HTTP headers or stdio environment variables.
Configuration
All configuration comes from environment variables. Start with .env.example. The usual settings are:
CHATZ_DB_DRIVER=sqlitefor one local container, orpostgresfor Compose and shared deployments.CHATZ_UPSTREAMSand the key variables named byapiKeyEnvfor models.CHATZ_SECRETS_KEYbefore storing MCP credentials. SetCHATZ_AUTH_PASSWORDLESS=truefor a single-user installation.LOG_LEVEL=debugfor local prompt troubleshooting. Debug logs may contain ordinary chat text, so do not send them to a shared log service.
Architecture
The Go service serves the API and embedded web app, stores chat data in Postgres or SQLite, calls models through Elelem, and connects MCP servers on demand. See the architecture guide for the details.
HTTP API
The versioned JSON and SSE API is under /api/v1. Read
api/api.yml for the contract. /healthz is available for
container health checks.
Deploy
Every push to main publishes psyb0t/chatz:latest. A v<semver> release tag
publishes the matching immutable psyb0t/chatz:v<semver> image. Deploy a tag,
not latest. Use SQLite for one local volume and Postgres for replicas,
networked storage, or an existing Postgres installation. For Docker Compose and
development, read getting started and
development.
License
See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
repogen
command
Command repogen generates the type-safe gorm/gen repositories from the models in internal/pkg/db/models.
|
Command repogen generates the type-safe gorm/gen repositories from the models in internal/pkg/db/models. |
|
internal
|
|
|
pkg/buildinfo
Package buildinfo exposes immutable identity compiled into a Chatz binary.
|
Package buildinfo exposes immutable identity compiled into a Chatz binary. |
|
pkg/config
Package config loads chatz's configuration from environment variables via gonfiguration.
|
Package config loads chatz's configuration from environment variables via gonfiguration. |
|
pkg/core/auth
Package auth is chatz's authentication domain: password hashing (bcrypt), server-side opaque session tokens (only the SHA-256 hash is stored; the raw token lives in the client's HttpOnly cookie), first-run admin bootstrap, and optional single-user passwordless auto-login.
|
Package auth is chatz's authentication domain: password hashing (bcrypt), server-side opaque session tokens (only the SHA-256 hash is stored; the raw token lives in the client's HttpOnly cookie), first-run admin bootstrap, and optional single-user passwordless auto-login. |
|
pkg/core/chat
Package chat adapts elelem's provider-neutral agent loop to chatz SSE.
|
Package chat adapts elelem's provider-neutral agent loop to chatz SSE. |
|
pkg/core/chats
Package chats is the chat business-logic layer: it owns the chat + message repositories and the model registry, and drives a turn end-to-end (demo interception, model resolution, the agentic turn loop, SSE streaming, and persistence).
|
Package chats is the chat business-logic layer: it owns the chat + message repositories and the model registry, and drives a turn end-to-end (demo interception, model resolution, the agentic turn loop, SSE streaming, and persistence). |
|
pkg/core/chats/fixedresponses
Package fixedresponses maps exact demo prompts to fixed assistant turns embedded at build time.
|
Package fixedresponses maps exact demo prompts to fixed assistant turns embedded at build time. |
|
pkg/core/chats/prompts
Package prompts holds generated, embedded LLM system-prompt fragments for the chat turn loop.
|
Package prompts holds generated, embedded LLM system-prompt fragments for the chat turn loop. |
|
pkg/db
Package db opens the selected persistent store, runs its embedded migrations, and wires the generated gorm/gen repositories' default query.
|
Package db opens the selected persistent store, runs its embedded migrations, and wires the generated gorm/gen repositories' default query. |
|
pkg/db/migrations
Package migrations embeds the SQL migration files into the binary so the binary is self-contained (no directory to mount).
|
Package migrations embeds the SQL migration files into the binary so the binary is self-contained (no directory to mount). |
|
pkg/db/models
Package models holds the plain Go structs that gorm/gen generates type-safe repositories from.
|
Package models holds the plain Go structs that gorm/gen generates type-safe repositories from. |
|
pkg/heartbeat
Package heartbeat is a tiny idle-heartbeat helper for long blocking calls (an LLM stream between deltas, a single MCP tool call) that otherwise produce zero log output while waiting.
|
Package heartbeat is a tiny idle-heartbeat helper for long blocking calls (an LLM stream between deltas, a single MCP tool call) that otherwise produce zero log output while waiting. |
|
pkg/http/api
Package api provides primitives to interact with the openapi HTTP API.
|
Package api provides primitives to interact with the openapi HTTP API. |
|
pkg/http/server
Package server implements chatz's generated StrictServerInterface on echo: session-cookie auth, model discovery, MCP management, and streaming chat.
|
Package server implements chatz's generated StrictServerInterface on echo: session-cookie auth, model discovery, MCP management, and streaming chat. |
|
pkg/logging
Package logging holds process-boot logging hardening that sits on top of slogconf's default handler: secret redaction (this file) and the gitignored chatz.log file sink (filesink.go).
|
Package logging holds process-boot logging hardening that sits on top of slogconf's default handler: secret redaction (this file) and the gitignored chatz.log file sink (filesink.go). |
|
pkg/mcp
Package mcp connects chatz to MCP servers (stdio + http) and imports their configuration.
|
Package mcp connects chatz to MCP servers (stdio + http) and imports their configuration. |
|
pkg/metrics
Package metrics owns chatz's Prometheus registry and the per-subsystem metric vectors.
|
Package metrics owns chatz's Prometheus registry and the per-subsystem metric vectors. |
|
pkg/operations
Package operations provides small operator-facing snapshots assembled from Chatz's already-running collaborators.
|
Package operations provides small operator-facing snapshots assembled from Chatz's already-running collaborators. |
|
pkg/secrets
Package secrets provides authenticated encryption (AES-256-GCM) for secret values stored at rest — MCP HTTP headers and stdio env vars.
|
Package secrets provides authenticated encryption (AES-256-GCM) for secret values stored at rest — MCP HTTP headers and stdio env vars. |
|
pkg/services/http-server
Package httpserver is the servicepack service that runs chatz's HTTP API.
|
Package httpserver is the servicepack service that runs chatz's HTTP API. |
|
pkg/tiktoken
Package tiktoken wraps the embedded tiktoken-go BPE codec so text can be split into model tokens with no runtime network fetch — the o200k_base vocabulary is compiled into the binary.
|
Package tiktoken wraps the embedded tiktoken-go BPE codec so text can be split into model tokens with no runtime network fetch — the o200k_base vocabulary is compiled into the binary. |
|
pkg/upstreams
Package upstreams discovers models across the configured OpenAI-compatible endpoints and routes a chosen model id back to the client that serves it.
|
Package upstreams discovers models across the configured OpenAI-compatible endpoints and routes a chosen model id back to the client that serves it. |
|
pkg/usage
Package usage decorates an elelem.Driver so every call emits LLM metrics and best-effort persists one llm_usage row.
|
Package usage decorates an elelem.Driver so every call emits LLM metrics and best-effort persists one llm_usage row. |
|
pkg/webassets
Package webassets embeds the built SvelteKit static SPA so the single Go binary serves both the API and the UI.
|
Package webassets embeds the built SvelteKit static SPA so the single Go binary serves both the API and the UI. |
|
pkg
|
|
|
http/api/client
Package client provides primitives to interact with the openapi HTTP API.
|
Package client provides primitives to interact with the openapi HTTP API. |
|
rebound
Package rebound retries context-aware operations with bounded exponential backoff.
|
Package rebound retries context-aware operations with bounded exponential backoff. |
|
tests
|
|
|
testinfra
Package testinfra brings up the real external dependencies chatz uses (a real Postgres via testcontainers-go) for integration tests.
|
Package testinfra brings up the real external dependencies chatz uses (a real Postgres via testcontainers-go) for integration tests. |
Click to show internal directories.
Click to hide internal directories.