Repolode
Submit
a16z-infra

a16z-infra/ai-town

A MIT-licensed starter kit for deploying and customizing AI Town, a virtual town where AI characters live, chat and socialize, built on Convex.

View on GitHubWebsite
Stars
10,676
Forks
1,227
Open issues
75
Last commit
2 months ago

What is it?

AI Town is a virtual town where AI characters live, chat and socialize. The project is a deployable starter kit for building your own version, inspired by the Generative Agents research paper. It is written in TypeScript and is designed to be extended, with a Convex backend that provides shared global state, transactions and a simulation engine.

The stack centers on Convex for the game engine, database and vector search, with Clerk as optional authentication. Characters are configured in data files, and the map can be built with Tiled and converted with a provided script. The default chat model is llama3 run through Ollama, but the app can also use Together.ai or any OpenAI-compatible API. Background music can be generated through Replicate, and the frontend rendering uses PixiJS.

Setup options include the standard Convex cloud workflow, a self-hosted Docker Compose setup, and deployment to Fly.io. The frontend can be deployed to Vercel, and local Ollama can be exposed to a cloud backend through a tunnel such as ngrok or Tunnelmole.

Key features

  • 01Simulated town where AI characters chat and socialize with each other.
  • 02Built on Convex, with shared state, transactions and a simulation engine.
  • 03Supports local inference via Ollama, plus Together.ai and OpenAI-compatible APIs.
  • 04Customizable characters, sprite sheets and maps edited with Tiled.
  • 05Optional background music generation via Replicate.
  • 06Runs locally, in Docker Compose, or deployed to Convex cloud, Fly.io and Vercel.

Use cases

  • Learning how generative agents can simulate social behavior in a virtual world.
  • Prototyping a multi-agent simulation or small multiplayer game with LLM-driven characters.
  • Building a customized virtual town with your own characters, stories and map.
  • Experimenting with local LLMs through Ollama in a self-contained setup.

Quick start

  1. 1

    Clone the repository

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

    Enter the project folder and install dependencies

    cd ai-town && npm install
  3. 3

    Start the app locally (log into Convex if prompted)

    npm run dev
  4. 4

    Open http://localhost:5173 in your browser

Things to know

  • Default setup needs a free Convex account and a local Ollama install with llama3 for AI chat.
  • Cloud LLM options such as OpenAI or Together.ai require paid API keys.
  • Windows users need WSL2 and an Ubuntu-style setup.

Topics

#ai#llm#simulation#multi-agent#typescript#convex#game#ollama

FAQ

What is ai-town?
A MIT-licensed starter kit for deploying and customizing AI Town, a virtual town where AI characters live, chat and socialize, built on Convex. AI Town is a virtual town where AI characters live, chat and socialize. The project is a deployable starter kit for building your own version, inspired by the Generative Agents research paper. It is written in TypeScript and is designed to be extended, with a Convex backend that provides shared global state, transactions and a simulation engine.
Is ai-town free to use? What license does it have?
ai-town is open source under the MIT license. Check the license terms before using it in commercial products.
Is ai-town still maintained?
Updated within 6 months. The last commit to ai-town was on Aug 26, 2026.
What can I use ai-town for?
Learning how generative agents can simulate social behavior in a virtual world. Prototyping a multi-agent simulation or small multiplayer game with LLM-driven characters. Building a customized virtual town with your own characters, stories and map. Experimenting with local LLMs through Ollama in a self-contained setup.
How do I install ai-town?
Clone the repository: git clone https://github.com/a16z-infra/ai-town.git Enter the project folder and install dependencies: cd ai-town && npm install Start the app locally (log into Convex if prompted): npm run dev Open http://localhost:5173 in your browser
Where can I get ai-town?
The source code and installation instructions are on GitHub: https://github.com/a16z-infra/ai-town

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects