Agnai runs a character chat server with or without a database

A chat server that starts without MongoDB

The headline decision is at the top of the quick start, marked as important. MongoDB and Redis are optional, and Agnaistic will run in Guest Only mode if MongoDB is not available. The README is explicit about what that means for users, since the database is optional and the application runs in anonymous-only mode if there is no database available, and anonymous users have their data saved to the browser's local storage. The data will persist, but it will not be shareable between devices or other browsers, and clearing the browser's application data or cookies will delete it. The project's own framing is AI roleplay chat with personalized characters using your favourite AI services, and it is based on the early work of the Galatea-UI project by PygmalionAI. The description calls it AI Agnostic, multi-user and multi-bot, and designed with scale in mind.

Installing from npm and where your files land

The package route is the shortest path to a running instance. The project is published as an NPM package and can be installed globally:

# Install or update:
npm install agnai -g
agnai

# View launch options:
agnai help

# Run with the Pipeline features
agnai --pipeline

The last flag turns on the optional pipeline features, which are the long-term memory and embedding parts. Storage is simple to reason about because it is a directory. When you use the NPM package, your images and JSON files are stored in `HOME_FOLDER/.agnai`, with the README giving the concrete paths for Linux, Mac and Windows. That location matters if you ever move between machines or back up your files. Note that this directory is separate from anonymous mode, whose data stays in the browser's local storage rather than on disk.

Docker, with and without MongoDB

The container route has two forms, and the difference is whether you want persistence for logged in users. With MongoDB you use the compose file from the project root:

docker compose -p agnai -f self-host.docker-compose.yml up -d

Without MongoDB, the image runs on its own with a single command:

docker run -dt --restart=always -p 3001:3001 ghcr.io/agnaistic/agnaistic:latest

The README annotates each flag, with `-dt` running the container detached, `--restart=always` restarting at start up or if the server crashes, and `-p 3001:3001` exposing port 3001 so the app is reachable at `http://localhost:3001`. The Dockerfile sets the working directory to `/app`, declares volumes for `/app/db`, `/app/assets`, `/app/dist/assets` and `/app/extras`, installs pnpm globally on a `node:20.18.1-bullseye-slim` base, and exposes ports 3001 and 5001, the second being the Python model service. The compose file in the repository root shows the two backing services, `mongo:8` on 27017 and `redis:7` on 6379.

Many AI services and several persona formats

The service support list is the practical reason to run your own. Agnaistic supports Kobold, Novel, AI Horde, Goose, OpenAI, Claude, Replicate, OpenRouter and Mancer. The persona side is more specific than the service side, because a roleplay character can arrive in several formats, and the project supports multiple persona schema formats: W++, the square bracket format, Boostyle and plain text. The features list also covers group conversations with multiple users and multiple bots, subscriptions, memory and lore books, generating characters with AI, and image generation through third party services. The multi-tenancy story is worth separating from the guest mode, because they are different products. With a database you get user authentication, per user settings for which AI service to use, and user generation presets, and each of those is what turns a single user toy into something several people can share.

The pipeline service and what it adds

The optional pipeline is a Python service alongside the Node server, and the pyproject for it shows the shape. It runs on Python 3.10 or later with `transformers`, `sentence-transformers`, `chromadb`, `Flask`, `uvicorn`, `numpy`, `accelerate`, `bitsandbytes` and `flexgen`, all under the package name `agn-ai`. The two features the README names are long-term memory, and Wikipedia article and PDF embedding, and both are the kind of thing that needs a model close to the data, which is why there is a separate service rather than a call out to a hosted API. The `npm run model` script installs Poetry into a virtual environment for it, and the Docker image exposes port 5001 alongside the application port, so the pipeline runs in the same container as the chat server.

settings.json, the small config surface

Self hosting knobs live in one file. To cater for the small tweaks and tuning people need at an application level, there is `settings.json`, and you can create a file called `settings.json` at the root level to apply changes across the entire application. The README says this is the place to ask for something to be catered for, and that the author will try to find a balance between catering to requests and not having them get out of control in the codebase. The examples it gives are a default memory book applied to all users, a different set of end tokens, and disabling anonymous access. The template file `template.settings.json` shows every available setting, and the currently supported custom setting listed is `baseEndTokens`, which adds extra response end tokens to the base set. You need to restart Agnaistic for changes to take effect.

Licence, tooling and the state of the project

The licence is AGPL-3.0, which for a server you host and share is the term to read carefully, since it reaches users who interact with the service over a network. The project is written in TypeScript with a SolidJS front end, Tailwind for styling, MongoDB for persistence and Redis for distributed messaging for websockets, with pnpm for dependency management and Poetry for the Python side. The developer tooling is documented in detail, with VSCode recommended along with Prettier and the Tailwind CSS IntelliSense extension, the `pnpm start` script running the Node server with `--inspect` so a debugger can attach, and the Redux Dev Tools extension wired to the front end state. Before opening a pull request the README asks you to run the format and typecheck commands, `pnpm run format:fix` and `pnpm run typecheck`, because the project uses ESLint, Prettier and TypeScript. The default branch is `dev`, there are no GitHub releases, and the last push was on 2026-06-15, so the repository is a moving target by design.

Editorial conclusion

Adopt Agnai when you want to run a character chat server yourself and point it at whichever AI services you already have accounts with, since the same instance can talk to Kobold, Novel, AI Horde, OpenAI, Claude, Replicate, OpenRouter and others, and it runs without a database at all. Do not adopt it expecting a hosted service with accounts and shared state, because the guest only mode keeps anonymous data in the browser's local storage and it cannot be shared between devices. Verify first whether your chosen AI service allows the kind of long roleplay traffic you intend, and note that the default branch is `dev` and the project publishes no GitHub releases, so you are tracking a moving branch.

Frequently asked questions

Official sources

1. agnaistic/agnai on GitHub
2. Issues
3. License: AGPL-3.0
4. Project website
5. README