Just-Chat is an open-source project for quickly creating and running LLM agent chat applications. Its core goal is to let users set up and start chatting with their own AI assistant in just a few simple steps.
Purpose
Just-Chat is aimed at developers or teams who want to quickly deploy a private AI chat assistant. It encapsulates agent execution, a chat interface, and search capabilities through containerization, reducing the complexity of environment configuration.
Main Capabilities
- One-click startup: after cloning the repository, run docker-compose up to start the entire application.
- Agent customization: configure the agent's personality and capabilities by editing the chat_agent_profiles.yaml file; example agents are already provided.
- Tool extension: add Python tools in the /agent_tools/ directory to add extra functionality and dependencies to the agent.
- Web chat interface: after startup, visit http://localhost:3000 to chat with the agent.
- Containerized operation: all components run in Docker containers, with no need to install Python or Node.js on the host machine.
- Model support: based on the just-agents library, agents are initialized from YAML and support mainstream models such as DeepSeek Reasoner, ChatGPT, and LLAMA3.3, but you need to configure API keys yourself. A free Groq key is provided by default, but the rate limits are strict, so using your own key is recommended.
- Semantic search: integrates MeiliSearch to support document retrieval based on meaning rather than keywords. Markdown files can be indexed through the API, and search functionality can be enabled in the agent system prompt.
- Data import and export: provides a MeiliSearch dump script to support backing up and restoring search indexes, making it easy to synchronize data between development and production environments.
How to Use
- Environment preparation: install Docker or Podman (Podman is recommended, as it is more modern and secure). The project provides detailed installation instructions for Linux and Windows, as well as an automated script for Ubuntu 22.04.
- Clone the repository and start: run docker-compose up (or use the corresponding Podman command). Containers run as the host user and group to avoid permission issues, and this can be adjusted by modifying USER_ID and GROUP_ID in docker-compose.yml.
- Access the interface: open in your browser http://localhost:3000 to start chatting.
- Custom configuration: edit chat_agent_profiles.yaml to customize the agent; add Python tools in /agent_tools/; modify docker-compose.yml for advanced settings.
- Semantic search configuration: after startup, visit localhost:9000/docs to index Markdown files using the API, then uncomment the search-related system prompt in chat_agent_profiles.yaml and set the index name.
- Data synchronization: use scripts/meilisearch_dump.py to create a dump, transfer it to the production environment via scp or rsync, and import it according to the instructions. Meilisearch 1.16+ supports export functionality, enabling incremental synchronization and conflict resolution.
Applicable Scenarios
- Quickly setting up an AI chat assistant for personal or internal team use.
- Developers who need to add custom tools and knowledge bases to agents.
- Environments that want to run LLM applications without installing Python/Node.js.
- Conversational scenarios that require semantic search and document retrieval capabilities.
Limitations
- Requires a Docker or Podman environment, and at least 4GB of memory is recommended.
- The default Groq key has strict rate limits, so it is recommended to obtain your own API key.
- The Podman v3 included with Ubuntu 22.04 is incompatible, and v4.9.3 or later must be installed manually.
- Containers using the :latest tag will not update automatically, so images need to be pulled manually on a regular basis.
- Importing a MeiliSearch dump requires the file to be named just_chat_rag.dump, and the data volume must be deleted to force the import.
- Some advanced features (such as export conflict resolution) require Meilisearch 1.16.0 or later.
