# AI Town: a Convex starter kit for generative-agent simulations

> AI Town is an MIT-licensed TypeScript starter kit from a16z-infra for running a virtual town of LLM-driven characters. It is a platform to fork and extend, not a finished game, and the Convex backend is the part that decides whether it fits your project.

**a16z-infra/ai-town** — A MIT-licensed, deployable starter kit for building and customizing your own version of AI town - a virtual town where AI characters live, chat and socialize.

- Repository: https://github.com/a16z-infra/ai-town
- Website: https://convex.dev/ai-town
- Stars: 10,535 · Forks: 1,203
- Language: TypeScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/a16z-infra-ai-town

## The problem AI Town solves, and who it is actually for

The repository describes itself as a deployable starter kit for building and customizing your own version of AI town, and names the research paper Generative Agents: Interactive Simulacra of Human Behavior as its inspiration. That framing matters more than the demo screenshot. The deliverable is a codebase you fork, not an application you sign up for.

The audience is narrow and specific. It is a developer who wants LLM characters that hold conversations, remember them and move around a shared world, and who would rather start from a working pipeline than from the paper's equations. The README states a secondary goal explicitly: to make a JS/TS framework available, since most simulators in this space, including the original paper's implementation, are written in Python. If your team writes TypeScript, that is the reason to look here.

It is not aimed at players. Nothing in the repository offers accounts, matchmaking or a hosted town. The characters are simulated agents, not other humans, which is worth stating plainly given how often that question comes up.

## Convex as the simulation engine, database and vector store

The stack section is unusually honest about the architecture: the game engine, the database and the vector search are all Convex. That single choice explains most of the project's shape. Shared global state, transactions and a simulation engine live in the backend, and the README argues this makes the foundation suitable from a small experiment up to a scalable, multi-player game.

Convex functions in the convex/ directory are the simulation. The frontend is a Vite and React app that renders through PixiJS and @pixi/react, and it reads and writes state through Convex rather than holding the world in browser memory. Vector search sits in the same backend, which is what lets characters retrieve relevant memories without a second service.

The trade-off is dependency depth. You are not adopting a library; you are adopting a backend platform and its deployment model. Teams already running Postgres and a queue will find that the simulation loop, the persistence layer and the retrieval layer cannot be swapped independently. The ARCHITECTURE.md file is the place to check before assuming otherwise, and the README does not present an alternative backend.

## Installing AI Town locally and running your first town

The standard setup requires a free Convex account. Clone the repository, install dependencies, then run the dev script, which starts the backend and frontend in parallel.

```bash
git clone https://github.com/a16z-infra/ai-town.git
cd ai-town
npm install
npm run dev
```

After that, the README says you can visit http://localhost:5173. The first run also needs a model. Ollama is the default, so install it, start it, and pull the default chat model. The README gives these steps directly.

```bash
ollama serve
ollama pull llama3
ollama run llama3
```

The default chat model is llama3 with mxbai-embed-large for embeddings. If you prefer to run the frontend and backend in separate terminals, the package.json exposes dev:frontend and dev:backend, and the backend variant tails logs as it syncs functions. The predev script runs convex dev --run init --until-success, which is the one-time initialization step the README references for the self-hosted path.

For a self-contained run without a Convex account, the Docker Compose file starts three services: frontend on 5173, backend on 3210 with the HTTP API on 3211, and dashboard on 6791. You generate an admin key inside the backend container and place it in .env.local.

```bash
docker compose up --build -d
docker compose exec backend ./generate_admin_key.sh
```

The README warns that running down and up again invalidates the key, so the .env.local values must be regenerated. The two keys are CONVEX_SELF_HOSTED_ADMIN_KEY, which the README says needs quotes around it, and CONVEX_SELF_HOSTED_URL set to http://127.0.0.1:3210.

## Swapping the LLM and the cost of local inference

The project is not tied to one provider. The README lists Ollama for local inference, Together.ai, and anything that speaks the OpenAI API, with an invitation for pull requests to add more cloud providers. Background music generation goes through Replicate using MusicGen, and pixel art generation also uses Replicate and Fal.ai.

Configuration runs through Convex environment variables rather than a config file. You can set the Ollama host so a containerized backend reaches an Ollama instance on the host machine, and the README suggests testing the connection from inside the container.

```bash
npx convex env set OLLAMA_HOST http://host.docker.internal:11434
docker compose exec backend /bin/bash curl http://host.docker.internal:11434
```

If the response says Ollama is running, the connection works. The model itself is set with OLLAMA_MODEL, or by editing convex/util/llm.ts. That file path is the honest answer to where model wiring lives, and it means changing providers is a code change, not a settings toggle.

The limitation here is operational rather than conceptual. Local inference means every character turn waits on your hardware, and the README offers no throughput guidance. Running the backend in the cloud while Ollama stays on your machine is possible, but the README treats it as a proxying arrangement you have to set up, not a supported default.

## Windows, Fly.io and the paths the README does not finish

Installation coverage is uneven, and that is worth knowing before you plan around it. The README has a dedicated Windows pre-requisites section, which suggests the standard flow does not work unchanged there, but the extracted content does not include its contents. Fly.io deployment is delegated to the ./fly directory rather than described in the README body.

A community fork offers a one-click install on Pinokio, described as being for people who want to run the project but not modify it. That is a meaningful distinction. The Pinokio path is a different codebase maintained by different people, so issues there are not issues in a16z-infra/ai-town.

Troubleshooting exists as a README section, and the Docker section points at it when the Ollama connection check fails. What the README does not document is rollback: if a backend deploy breaks the simulation, there is no described procedure for reverting to a previous Convex deployment. Plan for that gap rather than assuming it is covered.

## What you give up compared with a Python generative-agent stack

The obvious alternative is the Python ecosystem the README itself points to, including the original implementation behind the Generative Agents paper. The difference in approach is not language preference; it is where the simulation state lives. A typical Python agent simulation keeps state in process and persists it to a database you choose, which makes the loop easy to read and hard to scale past one machine. AI Town inverts this: state, transactions and vector search are Convex primitives, so the simulation is a set of backend functions and the frontend is a thin view.

That inversion buys multiplayer-shaped concurrency and a dashboard for inspecting state. It costs you the ability to run the simulation as a standalone script, and it makes Convex a hard requirement rather than an implementation detail. If you want to read the agent loop top to bottom in one file, or if your infrastructure standards exclude a hosted backend platform, the Python route is the better fit even though you would be rebuilding the frontend yourself.

A third option is the Pinokio fork mentioned above. It optimizes for running the town without touching code, which is the opposite trade-off from this repository's stated goal of being a platform meant to be extended.

## Licence, maintenance and what upgrading actually costs

The project is MIT-licensed. In practice that means you can fork it, modify it and ship it under your own terms, provided you keep the licence notice. It does not grant rights to the third-party assets credited in the README, which include tilesheets from OpenGameArt and UI elements by Mounir Tohami. Those carry their own terms, and the README lists them as credits rather than as a licence grant. This is not legal advice; if you plan to ship the default art, check each source.

The dependency surface is broad for a starter kit: Convex, Clerk for optional auth, PixiJS, React, Replicate, and a Jest and Vite toolchain. There are no retrieved releases, and package.json pins version 0.0.0 with private set to true, so versioning is not the mechanism by which you track upstream changes. The last push to the default branch was on 2026-08-26, which puts recent activity within the last month.

Upgrading therefore means tracking the main branch. Convex is a caret dependency at ^1.41.0, and the Docker Compose file pulls ghcr.io/get-convex/convex-backend:latest for the self-hosted backend. A moving latest tag on the backend image is the part most likely to surprise you during an upgrade, since the frontend and backend are expected to agree on protocol. Pin that image tag yourself if you self-host.

## Conclusion

Adopt AI Town if you want a TypeScript, Convex-backed base for a generative-agent simulation and you are willing to write your own characters, map and interaction rules. Do not adopt it if you want a playable game, a mobile app or a hosted service, because the repository does not provide one. Before committing, verify three things: that Convex is an acceptable dependency for your team, that your machine can pull llama3 and mxbai-embed-large, and that the ARCHITECTURE.md description of the simulation loop matches the behaviour you need.

## FAQ

### What is AI Town?

It is a deployable starter kit for building and customizing a virtual town where AI characters live, chat and socialize. It is inspired by the Generative Agents research paper, and the repository is written in TypeScript on top of Convex.

### How do you use AI Town?

Clone the repository, run npm install, then npm run dev, and visit http://localhost:5173. The default setup uses Ollama with llama3, so you also need Ollama running with that model pulled.

### Is AI Town a real game with real people?

The README describes a simulation of AI characters rather than a game with human players, and the repository contains no accounts or matchmaking. The characters are LLM-driven agents, not other people.

### Is AI Town safe to run?

The repository is MIT-licensed and the standard setup runs locally on http://localhost:5173 against a Convex backend. The self-hosted Docker path exposes the backend on port 3210, the HTTP API on 3211 and the dashboard on 6791, and the README has you generate an admin key for dashboard access.

### Can you download AI Town for Android?

The repository does not describe an Android build. The supported paths in the README are the standard Convex setup, Docker Compose with a self-hosted backend, a Fly.io deployment under ./fly, and a community fork offering a one-click Pinokio install.

## Sources

- [a16z-infra/ai-town on GitHub](https://github.com/a16z-infra/ai-town)
- [Issues](https://github.com/a16z-infra/ai-town/issues)
- [License: MIT](https://github.com/a16z-infra/ai-town/blob/main/LICENSE)
- [Project website](https://convex.dev/ai-town)
- [README](https://github.com/a16z-infra/ai-town/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/a16z-infra-ai-town