pAIring quick start

Decide your layout first

This guide sets up a single node, where pAIring and the engine run together on the same node. If the heavy model work should run on other servers, read Deployment layouts first. You can switch later.

Install

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env   # then set a real SECRET_KEY
.venv/bin/python run.py

On Linux or macOS you can run bash scripts/install.sh instead. It does the same steps with extra checks.

To run it as a service on Linux, edit the systemd unit template in scripts/pairing.service and enable it with systemctl enable.

Log in

1. Open http://localhost:8000 in your browser. On another computer, use the server’s address instead of localhost.

2. Log in with the starter account:

   Username	Password
   admin	admin

   pAIring creates this admin account automatically the first time it starts.

3. After logging in you see the chat screen. As an admin you also get Admin settings, Stats, Connectors and Cluster in the sidebar.

4. Create accounts for other people under Admin settings → Users. Each person gets their own private chats. See Admin settings.

Good to know

• Too many wrong passwords lock the login for a while. After 5 failed attempts from one address, further attempts are refused for 15 minutes.
• The app listens on port 8000 on all network addresses by default. To change this, set APP_PORT or APP_HOST in your .env file.
• If you cannot open the page from another computer, check that the port is open in the server’s firewall.
• To use pAIring from the internet, put a reverse proxy with HTTPS in front of it. Never expose it with the default password.

First steps

1. Open Settings → Inference engines and choose your inference engine. llama.cpp and Matricxon are supported, and both can be installed from there. By default they share one models folder, so a model you download is ready for both. Matricxon has more options but still has some limitations, described in its docs.
2. Open Settings → Models and download some models. Embedding models are needed for the knowledge base. Vision projectors are needed for image understanding.
3. For images, open Settings → Image and install stable-diffusion.cpp. On Linux you can also build it from source, which needs git, cmake and g++. Then download a diffusion model, such as SD-Turbo, choose it in the engine’s Model list and press Start.
4. Open Settings → System and set the important parameters, such as the default vision model.
5. Run a few tests.

Production notes

• Tune the cache settings. Matricxon lets you manage its persistent cache closely.
• Hardware matters a lot. A single computer, or several working as a cluster, sets how fast the system runs.
• Do not expose more models than your RAM or VRAM can hold. On a 32 GB computer, expose two or three models that all fit in memory. In production, models should stay loaded.
• MySQL and multi-server deployment are supported.
• Go through the security checklist before others use it.