Getting Started With AbraTabia AI Storyteller
Requirements
PHP 8.1 or newer with the curl, pdo_sqlite, and dom extensions, all three ship in standard PHP builds. You also need an API key from an LLM provider: Anthropic, OpenAI, OpenRouter, or a local runner like Ollama or LM Studio that exposes an OpenAI compatible endpoint. There is no database server to install, the SQLite file is created automatically in data/.
Step 1: Install and Run the Server
All three install paths start the same way: copy config.sample.php to config.php and edit it, adding your LLM key and setting apiKey and adminPassword to long random strings.
Local development uses PHP's built-in server:
cp config.sample.php config.php
# edit config.php: add your LLM key, set apiKey and adminPassword
php -S localhost:8080 -t publicDocker is two commands after the config edit: docker compose up --build, and the app is at http://localhost:8080/ with the same admin and demo pages.
Shared hosting means uploading the project and pointing your docroot or a subdomain at the public/ folder. If you can only upload into an existing docroot, put everything in a subfolder and the API lives at yoursite.com/subfolder/public/api.php.
Step 2: Configure the Provider and Embeddings
Everything lives in config.php. The chat side is one choice: set chatProvider to anthropic with your Anthropic key and model, or to openai with a key, base URL, and model for any OpenAI compatible API, which is also how you point at OpenRouter, Ollama, or LM Studio.
The knowledge base needs an embeddings driver. local uses OpenAI embeddings stored in SQLite, upstash uses Upstash Vector, and off disables the knowledge base so bots run from rules alone. One pairing note worth memorizing: the local driver needs an OpenAI key, so if you chat through Anthropic, use Upstash for embeddings or set the driver to off.
| Setting | What it does |
|---|---|
chatProvider | "anthropic" or "openai" |
anthropicApiKey, anthropicModel | Anthropic credentials and default model |
openaiApiKey, openaiBaseUrl, openaiModel | OpenAI compatible credentials, base URL, default model |
maxTokens | Max tokens per chat response |
embeddingsDriver | "local", "upstash", or "off" |
openaiEmbeddingModel | Embedding model for the local driver |
upstashVectorUrl, upstashVectorToken | Upstash Vector REST credentials |
apiKey | The key game clients must send with every API call |
adminPassword | Password for admin.php and the crawl endpoint |
corsOrigin | Which browser origins may call the API, "*" or your game's origin |
dbPath | SQLite file location |
conversationDays | How long conversations are kept |
Step 3: Create Your First Bot
Open admin.php in the browser and log in with your admin password. Create a bot, pick its type, storyteller for an immersive narrator, gamehost for a turn-based game master, or assistant for grounded question answering, and give it rules describing its personality, world, and boundaries. The bot ID you choose here is what your game sends with every request.
If the bot should know your world, feed the knowledge base now: paste lore text in the admin area, push it through the API, or crawl a website. The knowledge base guide covers all three routes.
Step 4: Test on the Demo Page
Open demo.php and talk to your bot from the browser. This is the fastest iteration loop for tuning rules: chat, notice what feels off, adjust the bot in the admin area, chat again. Get the personality right here before any game code exists, because prompt problems are much easier to see in a plain chat window than through your game's UI.
Step 5: Call the API From Your Game
Your game talks to one endpoint. Send the bot ID, the player's message, and a blank conversation ID to start, then echo back the returned convoID with every following message:
curl -X POST http://localhost:8080/api.php/chat \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_KEY" \
-d '{"chatbotID": "my-storyteller", "prompt": "I push open the tavern door.", "convoID": ""}'The response carries the bot's reply in message, an action word when something game-relevant happened, and the convoID to continue the conversation. Every request and response field is documented in the chat API reference.
Before You Go Live
Three production habits: serve over HTTPS, lock corsOrigin to your game's origin, and remember that every chat call spends LLM credits, so set a spending limit with your provider. For public browser games, a key in client code is visible to players, either accept that with spend limits in place or route the calls through your own game server so the key stays private.
Setup is one config file: copy it, add an LLM key and two passwords, and run the server locally, in Docker, or on shared hosting. Create and tune your bot in the admin area, prove it on the demo page, and your game is one POST request away from a storyteller.