AI Town
A full-stack starter kit for building customizable virtual towns inhabited by AI characters.
Per-dimension scores and reasoning
Evidence shows: API keys are managed via environment variables, no hardcoded credentials found; but no user confirmation mechanism, limited data flow description, lack of sensitive data handling details, dependency security not mentioned, external effects (e.g., network calls) not clearly stated, rollback only via database reset, source attribution only through acknowledgments in README. Deductions: lack of user confirmation, data flow transparency, and sensitive data handling details.
Evidence shows: README and code structure are consistent, multiple deployment methods provided; but dependency availability not verified, failure messages provided in troubleshooting section. Deductions: dependency availability not verified, failure messages coverage incomplete.
Evidence shows: targeted at developers and enthusiasts, multiple deployment scenarios and customization options; but trigger precision (e.g., environment variable configuration) not precise enough, environment fit (e.g., Windows) documented. Deductions: insufficient trigger precision.
Evidence shows: README structure clear, installation notes detailed, naming stable, examples and FAQ present, MIT license explicit; but no versioning changelog, maintenance responsibility not clear. Deductions: missing versioning changelog and maintenance responsibility.
Evidence shows: high output usability, provides runnable simulated world, clear marginal value, reasonable cost-benefit (free open source). Deductions: no major deductions.
Evidence shows: claims in README partially traceable, but lack external verification, facts and inferences not clearly separated. Deductions: lack of external verification and fact-inference separation.
- Project relies on external services (Convex, Ollama, OpenAI, etc.), be mindful of API key management and data privacy.
- No user confirmation mechanism, may automatically perform external calls.
- Missing versioning changelog, maintenance responsibility unclear.
What does this agent do, and when should you use it?
AI Town is a deployable starter kit for a virtual town where AI characters live, chat, and socialize. Its PixiJS-powered <Game/> component handles interactions, rendering, and background-music playback, while Convex supplies shared global state, transactions, a simulation engine, database storage, and vector search. Character definitions, stories, and spritesheet references live in data/characters.ts; convex/init.ts loads the map, which can be replaced through Tiled and convertMap.js. The default local setup uses Ollama with llama3 for chat and mxbai-embed-large for embeddings, with documented configuration paths for OpenAI, Together.ai, and other OpenAI-compatible APIs. It can run through the standard Convex workflow or a self-hosted Docker Compose stack, with the frontend served at http://localhost:5173.
npm run dev starts the application and serves its browser UI at http://localhost:5173; npm run dev:frontend and npm run dev:backend can run the two sides separately. The Convex backend stores shared simulation state and memory embeddings, then uses the configured chat model to generate character conversations; by default it connects to Ollama for llama3 chat and mxbai-embed-large embeddings. It reads character, story, spritesheet, and movement data from data/characters.ts, loads map data through convex/init.ts, and renders interaction through PixiJS in <Game/>. Optionally, convex/music.ts uses Replicate and MusicGen to generate daily background music, with scheduling configured in convex/crons.ts. Operational commands including testing:stop, testing:resume, testing:kick, testing:archive, testing:wipeAllTables, and init control or reset a world.
- A TypeScript developer building an interactive pixel town from original character descriptions and stories can edit data/characters.ts and reinitialize the world.
- A team experimenting locally with AI-character dialogue and memory retrieval can use the default Ollama, llama3, and mxbai-embed-large configuration.
- A developer prototyping a multiplayer simulation game that needs transactions and shared world state can deploy the application on Convex.
- A developer who needs local infrastructure for the frontend, backend, and dashboard can use the self-hosted Convex Docker Compose setup.
- An engineer connecting a pre-existing OpenAI-compatible model service to character dialogue can configure LLM_API_URL, LLM_API_KEY, LLM_MODEL, and LLM_EMBEDDING_MODEL.
- A game-content creator replacing the town environment can export a two-layer map from Tiled and convert it with data/convertMap.js.
What are this agent's strengths and limitations?
- Combines real-time shared state, transactions, a simulation engine, database storage, and vector search in the Convex backend for a continuously running world.
- Provides explicit files and conversion steps for replacing characters, stories, spritesheets, and maps instead of limiting customization to prompts.
- Supports a fully local default path with Ollama and documents configuration for OpenAI, Together.ai, and OpenAI-compatible services.
- Offers both a standard Convex deployment path and a Docker Compose option that runs the frontend, backend, and dashboard together.
- The core architecture depends on Convex; the standard development workflow requires a Convex account, even though self-hosting is available.
- The default model path depends on a local Ollama installation, and Docker deployments need container-to-Ollama network configuration.
- Changing LLM providers or embedding models requires wiping data and starting over because vector dimensions must match the embedding model.
- Changing character data requires testing:wipeAllTables, which deletes all existing data.
- A world pauses after five minutes of browser inactivity unless the page is loaded, it is manually resumed, or the inactive-world cron is changed.
How do you install or deploy this agent?
For the standard setup, run git clone https://github.com/a16z-infra/ai-town.git && cd ai-town && npm install, then npm run dev. This flow requires signing in to a Convex account; open http://localhost:5173 afterward. For default local inference, install and start Ollama, run ollama pull llama3, then verify it with ollama run llama3. For OpenAI, set EMBEDDING_DIMENSION to OPENAI_EMBEDDING_DIMENSION in convex/util/llm.ts and run npx convex env set OPENAI_API_KEY 'your-key'. For self-hosting, run docker compose up --build -d, then docker compose exec backend ./generate_admin_key.sh; configure CONVEX_SELF_HOSTED_ADMIN_KEY and CONVEX_SELF_HOSTED_URL, and run npm run predev.
How do you use this agent?
Open http://localhost:5173 after the first start to run and inspect the town. To change characters or stories, edit data/characters.ts, then run npx convex run testing:wipeAllTables and npm run dev so the initial character data is uploaded again; the wipe command removes existing data. To replace the map, export JSON from Tiled with bgtiles and objmap layers, run node data/convertMap.js <mapDataPath> <assetPath> <tilesetpxw> <tilesetpxh>, and use the generated converted-map.js. For production, run npx convex deploy followed by npx convex run init --prod; the frontend can be deployed with vercel --prod.
How does this agent compare with similar options?
For deployment, the standard Convex setup is positioned for local or cloud development and requires a Convex account, while Docker Compose self-hosts the frontend, backend, and dashboard for users comfortable with Docker. The repository also mentions a community Pinokio fork intended for one-click running without modification.