---

name: server-setup-and-cli description: "Install, initialize, configure, and start Langchain-Chatchat with the chatchat CLI, data root, model providers, and deployment options." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Server Setup and CLI

Use this sub-skill for Langchain-Chatchat installation, CHATCHAT_ROOT, YAML configuration, chatchat init, chatchat kb, chatchat start, Docker/Xinference deployment planning, and model-provider setup.

Read first

• references/cli-reference.md lists verified CLI commands and flags.
• references/configuration.md explains CHATCHAT_ROOT, generated YAML files, and important settings groups.
• references/model-provider-setup.md explains provider separation, model names, and Xinference/Ollama/LocalAI/FastChat/One API style configuration.
• references/deployment.md covers pip/source/Docker deployment choices and why AutoDL scripts are not bundled as runnable helpers.
• references/troubleshooting.md gives setup-specific symptoms and recovery steps.
• Run scripts/chatchat_config_audit.py against an initialized data root to check expected config/data files without starting services.

Setup workflow

1. Choose environment. Use Python 3.10 or 3.11. Prefer a clean Chatchat environment. Keep heavy model-serving frameworks in separate envs/containers unless the user explicitly wants a combined setup.
2. Install package. For normal users, use python -m pip install -U langchain-chatchat. For source development, install the server package editable from the server package root.
3. Pick data root. Set CHATCHAT_ROOT to a persistent directory if the current working directory is not the desired data/config location.
4. Initialize. Run chatchat init before any service startup. Do not use --recreate-kb until embedding provider settings are valid.
5. Edit YAML. Update model platform, default LLM, default embedding model, server host/port, KB/vector-store settings, and tool settings as needed.
6. Rebuild or update KB. Run chatchat kb -r for full vector rebuild only after the embedding model is reachable. Use update/increment/prune flags for lighter maintenance.
7. Start service. Use chatchat start --api, chatchat start --webui, or chatchat start -a.
8. Validate endpoints. Open API docs at the API service root redirect or use API/SDK probes from sibling sub-skills.

CLI quick reference

chatchat --help
chatchat init --help
chatchat kb --help
chatchat start --help

Common command sequence:

export CHATCHAT_ROOT=/path/to/chatchat-data
chatchat init
# edit generated YAML files: model_settings.yaml, kb_settings.yaml, basic_settings.yaml, tool_settings.yaml, prompt_settings.yaml
chatchat kb -r
chatchat start -a

If chatchat kb -r fails, do not retry blindly. Confirm the embedding provider endpoint and model name first.

Boundary with sibling sub-skills

• After the API/WebUI process is running, use ../knowledge-base-and-api/SKILL.md for route payloads, RAG modes, tools, and vector-store API calls.
• Use ../python-sdk-and-adapters/SKILL.md for SDK clients, open_chatcaht, and LangChain adapter classes.
• Return here when an API/SDK failure points to missing config, wrong model names, CHATCHAT_ROOT, provider reachability, or service startup.

Safety rules

• Do not start Docker Compose, model downloads, or AutoDL process-killing scripts without explicit user approval.
• Do not run chatchat kb --clear-tables, prune commands, or --recreate-kb against user data until the target CHATCHAT_ROOT and backup status are clear.
• Do not claim GPU/provider readiness from package import or CLI help. Provider readiness requires provider-specific checks.