pAIring configuration

Most settings live in the app and are changed from Admin settings. A few deployment facts are read at start-up from environment variables, or from a .env file in the project folder. Real environment variables win over .env. Start from the example:

cp .env.example .env

All of them are read in app/config.py. Restart pAIring after changing them.

Server and sessions

Variable	Default	Meaning
APP_HOST, APP_PORT	0.0.0.0, 8000	Where pAIring listens
SECRET_KEY	random per start	Signs login sessions and encrypts stored secrets. Set it
SESSION_COOKIE_SECURE	false	Set true once pAIring is served over HTTPS

Generate a secret key with:

python3 -c "import secrets; print(secrets.token_hex(32))"

Without SECRET_KEY

A new random key is made on every start. Everyone is logged out after each restart, and saved secrets (proxy password, MCP headers, connector keys, the cluster admin secret) can no longer be read. Set it once and keep it.

Storage

Variable	Default	What it holds
DATA_DIR	./data	The SQLite database and uploaded documents
DATABASE_URL	SQLite file in DATA_DIR	The database connection
KNOWLEDGE_DIR	./knowledge	Shared knowledge-base files
ATTACHMENTS_DIR	./attachments	Files attached to chat messages
AVATARS_DIR	./avatars	Profile pictures
IMAGES_DIR	./generated_images	Images from the Images page
EXTERNAL_DIR	./external	Engines pAIring installs for you

Moving a server

An explicit DATABASE_URL wins over DATA_DIR. Setting DATA_DIR alone does not move a database you already set. To move everything, set both.

To switch to MySQL, use Admin settings → System → Database. It tests the connection and builds the schema for you.

Database migrations

Variable	Default	Meaning
AUTO_MIGRATE	true	Update the database schema on every start

With several pAIring servers on one database, set AUTO_MIGRATE=false on all of them, and run the update once yourself before starting them:

.venv/bin/alembic upgrade head

Starting several servers that all migrate at once can fail.

Models

Variable	Default	Meaning
DEFAULT_MODEL	a small Gemma 4 model	Model for a chat that names none
EMBEDDING_MODEL	nomic-embed-text v1.5	First embedding model for the knowledge base
EMBEDDING_NUM_CTX	512	The embedding model’s context size

Both models can be changed later from Admin settings → System → Default models.

Image engine

Variable	Default	Meaning
SDCPP_HOST	http://localhost:8189	Address of stable-diffusion.cpp’s server. Its port comes from here

Fixed limits

These are built in and cannot be changed with a variable:

Limit	Value
Attachment size	10 MB per file
Attachments per message	5 documents and 1 image
Profile picture	2 MB
Knowledge-base chunk	500 characters, with 75 overlapping