Skip to content
Get packs

AI Town

A starter kit for building your own town where AI characters live, chat and socialize.

GitHub Download source
Stars
10.7k
Forks
1.2k
Licence
MIT
Language
TypeScript
Last update
2 months ago
Type
App

What it is

AI Town is a virtual town where AI characters live, chat and socialize with each other. It is a deployable starter kit meant to be customized, built on Convex as the backend and using a language model for the characters' conversations. The project is inspired by the Generative Agents research paper and is written in TypeScript.

  • Run a local town of AI characters using Ollama and the default llama3 model
  • Swap the chat model to OpenAI, Together.ai, or another OpenAI-compatible API
  • Customize the simulated world and characters in your own copy of the code
  • Deploy the app to the cloud via Convex or self-host the backend with Docker Compose

Great for

  • Developers who want a TypeScript starting point for AI simulations
  • Students exploring how AI agents can interact in a shared world
  • Hobbyists who want to run a local AI town using Ollama
  • Teams wanting a base for a multiplayer game with AI characters

Not ideal for

  • People who want a finished game to play without any setup, since it is a starter kit to build on
  • Those who need a Python-based simulator, because the project is a JS/TS framework by design
  • Users without Docker or a Convex account who want to modify the code, as those are needed for the standard paths
Step-by-step guide: how to use AI TownInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Clone and build from source

    You'll need: Node.js · npm · A Convex account (free) for the standard setup · Ollama for local inference, or an API key for a cloud LLM · Docker (optional, for the self-hosted Docker Compose setup)

    Clone the repository

    git clone https://github.com/a16z-infra/ai-town.git

    Enter the project folder

    cd ai-town

    Install dependencies

    npm install

    Run the app

    npm run dev
  2. 2

    Run it

    • Install Ollama and run `ollama pull llama3` to download the default model
    • Run `npm install` and then `npm run dev` in the project folder
    • Visit http://localhost:5173 in your browser
  3. 3

    Get the most out of it

    • Set NUM_MEMORIES_TO_SEARCH to 1 in constants.ts if conversations become slow
    • Change the chat model with the OLLAMA_MODEL environment variable or in convex/util/llm.ts
    • Use the Docker Compose setup to run the frontend, backend, and dashboard together
    • Connect a cloud deployment to local Ollama by following the README's proxy instructions
    • Use any OpenAI-compatible API by setting LLM_API_URL, LLM_API_KEY, and LLM_MODEL

Downloads

Source code (.zip)main branch · straight from GitHubOfficial website & docsconvex.dev/ai-town

Strengths

  • Provides a foundation with shared global state, transactions, and a simulation engine, per the README
  • Supports several LLM options, including fully local inference through Ollama
  • MIT licensed and designed to be extended

Trade-offs

  • Setup involves several moving parts (Convex, an LLM provider, possibly Docker), so it is not a quick click-and-run experience
  • Changing the LLM provider or embedding model requires deleting your data, according to the README
  • The README is truncated and some details of customization are not covered in the excerpt

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.