ai-town
AI Town is a deployable starter kit for building virtual towns where AI characters live, chat, and socialize. It provides a full-stack foundation with shared state, transactions, and a simulation engine, inspired by the Generative Agents research paper. It is for developers who want to create and customize their own AI-powered social simulations or games.
✨ Key features
- Backend with shared global state, transactions, and simulation engine
- Configurable LLM support: Ollama, OpenAI, Together.ai, or OpenAI-compatible APIs
- Customizable characters, stories, and spritesheets
- Map editing with Tiled and conversion script
- Optional background music generation via Replicate
- Multiple deployment options: Convex cloud, Docker Compose, Fly.io
🎯 Use cases
- Build a virtual town with AI characters that chat and socialize
- Create a multiplayer game with AI-driven NPCs
- Experiment with generative agent simulations in JavaScript/TypeScript
- Prototype social AI experiences with customizable characters and environments
📦 Installation
🧰 Requirements: Requires Node.js (v18 recommended), npm, and a Convex account for standard setup; alternatively use Docker Compose for self-hosted backend. LLM API keys needed for cloud providers (OpenAI, Together.ai) or local Ollama installation.
git clone https://github.com/a16z-infra/ai-town.git
cd ai-town
npm install
To run it:
npm run dev
You can now visit http://localhost:5173.
If you'd rather run the frontend and backend separately (which syncs your backend functions as they're saved), you can run these in two terminals:
npm run dev:frontend
npm run dev:backend
See package.json for details.
🚀 Usage
After installation, run npm run dev and open http://localhost:5173. The app will attempt to connect to Ollama by default; ensure Ollama is running and llama3 model is pulled. For cloud LLMs, set environment variables as described in the README.
⚠️ Good to know
The simulation pauses after 5 minutes if the window is idle; you can comment out the cron to run continuously. Changing LLM provider or embedding model requires wiping the database and starting over.
❓ FAQ
What are the default LLM and embedding models?
The default chat model is llama3 and embeddings use mxbai-embed-large, both running locally via Ollama.
Can I use OpenAI or Together.ai instead of Ollama?
Yes, you can configure OpenAI or Together.ai by setting the appropriate API key and changing the embedding dimension in convex/util/llm.ts.
How do I reset the world and start over?
You can archive the current world with npx convex run testing:archive and then create a fresh world with npx convex run init.
How do I stop the backend if it's too active?
Use npx convex run testing:stop to stop the engine and agents, and npx convex run testing:resume to restart them.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.