Method 1: Docker Compose (self-hosting)
This is the fastest path to running the full AllCodex ecosystem.Prerequisites
- Docker installed.
- An OpenRouter API Key (required by AllKnower for parsing features).
1. Download the Docker Compose file
Create a directory for AllCodex and downloaddocker-compose.yml:
2. Configure environment variables
Create the env directories and configuration files:OPENROUTER_API_KEY to /etc/allcodex/allknower.env:
3. Launch the stack
Run the compose file in detached mode:Method 2: Local development (mprocs)
Use this method if you want to run the codebase from source or contribute to AllCodex.Prerequisites
- Node.js v22.x (AllCodex Core requires Node v22; Node v26 is not supported due to native DB bindings).
- Bun (required by AllKnower and Portal).
- pnpm v10+ (required by Core).
- PostgreSQL running on your local machine.
- mprocs (
npm install -g mprocsorbrew install mprocs) to orchestrate the services.
1. Clone the repository (with submodules)
Ensure you pull all submodules during cloning:2. Install dependencies and build
3. Set up AllKnower env
Copy.env.example in allknower to .env and fill in your PostgreSQL URL and OpenRouter key:
4. Run all services with mprocs
From the repository root directory, run:- AllCodex Portal on http://localhost:3000
- AllKnower on http://localhost:3001
- AllCodex Core on http://localhost:8080
Zero-login auto-provisioning
On your very first run, AllCodex performs an automatic boot-chain:- Core sets its admin password from environment configurations.
- AllKnower registers a default owner account, obtains an ETAPI security token from Core, and encrypts it at rest.
- Portal intercepts your first visit, retrieves the owner session, and logs you in.
Your first brain dump
Once in the Portal, follow these steps to see the parser in action:1
Write or paste raw text
Click the Brain Dump tab in the Portal. Paste a rough description of an NPC, location, or historical event.
Example:
“Lord Michael Ashvane is an aging paladin of the Dawn Shield faction. He guards Blackstone Keep in the eastern marches of Solara.”
2
Process the dump
Click Submit. The AI streams entities (such as Lord Michael Ashvane, Dawn Shield, Blackstone Keep, Solara) on screen.
3
Apply the lore
Click Apply to Database. The AI creates separate notes for each entity in AllCodex Core, links them to templates, and attaches canonical attributes (like
#loreType = "character" and affiliation = "Dawn Shield").4
View the graph
Go to the Relationship Graph tab. The interactive React Flow canvas displays the new entities and their connections.