Skip to content
Get packs

Guide · Open source

How to use AI Town: install, run locally with Ollama and customize

Updated · written with AI from the project's own documentation and checked against our catalogue data

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 cloned, run and customized, built on Convex as the backend and using a language model for character conversations. This guide shows you how to get it running on your machine, choose an LLM, and where to look when you want to change the simulation.

AI Towna16z-infra/ai-town · ★ 10.7k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the a16z-infra/ai-town repository and enter the ai-town folder.
  2. 2Install dependencies. Run npm install. You will be asked to log into Convex if you have not already.
  3. 3Start the app. Run npm run dev and open http://localhost:5173 in your browser.
  4. 4Install Ollama and pull a model. Install Ollama, run ollama serve if needed, then run ollama pull llama3.
  5. 5Point the app at your LLM. Keep the Ollama default, or set an OpenAI, Together.ai or OpenAI-compatible API key with npx convex env set.
  6. 6Customize the town. Edit convex/util/llm.ts or constants.ts to change the model or memory search settings, and read package.json for the available scripts.

What you need before you start

The standard setup needs Node.js and npm, plus a Convex account, which is free. If you want to run models locally, you also need Ollama. Docker is optional and only needed for the self-hosted Docker Compose setup.

If you use Windows, the README has a separate Windows pre-requisites section, so read that before running the commands below.

  • Node.js and 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)

Install and run AI Town with the standard setup

Clone the repository, move into the project folder and install dependencies. The README says this step will require logging into your Convex account if you have not already done so.

To start the app, run the dev command. When it is running, open http://localhost:5173 in your browser.

If you prefer to run the frontend and backend separately, so backend functions sync as you save them, run the two dev scripts in two terminals.

  • Frontend and backend together: npm run dev
  • Frontend only: npm run dev:frontend
  • Backend only: npm run dev:backend
git clone https://github.com/a16z-infra/ai-town.git cd ai-town npm install npm run dev

Run AI Town locally with Ollama

By default, the app tries to use Ollama to run entirely on your machine. Install Ollama, start it, then download the default chat model, llama3. The README's default embedding model is mxbai-embed-large.

You can test that the model works by running it directly in Ollama before you start the town.

  • Download and install Ollama from ollama.com
  • Open the Ollama app or run ollama serve; the command warns you if it is already running
  • Run ollama pull llama3 to download the model
  • Test with ollama run llama3
ollama pull llama3 ollama run llama3

Connect a cloud LLM instead of Ollama

If you do not want local inference, the README documents OpenAI and Together.ai. Each one needs an API key stored in your Convex environment, and a matching change to the embedding dimension in convex/util/llm.ts.

For other services, the README says any OpenAI-compatible API can be used, such as Anthropic, Groq or Azure, by setting LLM_API_URL, LLM_API_KEY, LLM_MODEL and LLM_EMBEDDING_MODEL. If the provider does not require a key, leave LLM_API_KEY unset.

  • OpenAI: set OPENAI_API_KEY; optionally OPENAI_CHAT_MODEL and OPENAI_EMBEDDING_MODEL
  • Together.ai: set TOGETHER_API_KEY; optionally TOGETHER_CHAT_MODEL and TOGETHER_EMBEDDING_MODEL
  • Other OpenAI-compatible APIs: set LLM_API_URL, LLM_API_KEY, LLM_MODEL, LLM_EMBEDDING_MODEL
npx convex env set OPENAI_API_KEY 'your-key'

Run the self-hosted Docker Compose setup

If you want to try the app without a Convex account and you are comfortable with Docker, the README describes a Docker Compose setup that runs the frontend, backend and dashboard together. Start it in the background with the -d flag.

After the first run, you can stop and start the services. To deploy from the Convex CLI or log into the dashboard, generate an admin key, add it to .env.local, then run the one-time predev setup. If you run down and up, you must generate the key again.

  • Frontend: http://localhost:5173
  • Backend: http://localhost:3210 (3211 for the HTTP API)
  • Dashboard: http://localhost:6791
docker compose up --build -d docker compose exec backend ./generate_admin_key.sh npm run predev

Customize your own simulation

The project is designed as a foundation to extend. To change which model is used, adjust convex/util/llm.ts or set OLLAMA_MODEL with npx convex env set. The README also says that if you change the LLM provider or embedding model, you should delete your data, because stored memories were created with the old model.

If conversations are slow with Ollama, the README suggests setting NUM_MEMORIES_TO_SEARCH to 1 in constants.ts to reduce prompt size.

  • Model selection: convex/util/llm.ts or the OLLAMA_MODEL variable
  • Embedding model: OLLAMA_EMBEDDING_DIMENSION in convex/util/llm.ts, plus OLLAMA_EMBEDDING_MODEL
  • Speed tuning: NUM_MEMORIES_TO_SEARCH in constants.ts
npx convex env set OLLAMA_MODEL llama3

What people use it 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 that want a base for a multiplayer game with AI characters

Frequently asked questions

Is AI Town free to use?

AI Town is released under the MIT licence. The standard setup needs a Convex account, which the README describes as free. Cloud LLM providers such as OpenAI or Together.ai require their own API keys, so check their pricing separately.

What are the requirements to run AI Town?

The standard setup needs Node.js, npm and a Convex account. Ollama is needed for local inference, or you can use an API key for a cloud LLM. Docker is optional and only needed for the self-hosted Docker Compose setup.

Can I run AI Town without Docker?

Yes. The standard setup uses a Convex account and the npm commands, and does not require Docker. Docker is only needed for the self-hosted Docker Compose path.

Can AI Town run fully offline with Ollama?

The README says the default configuration tries to use Ollama to run entirely locally, using llama3 for chat and mxbai-embed-large for embeddings. Once models are downloaded, the local setup does not depend on a cloud LLM, though the Convex backend is still part of the standard setup.

Why does my AI Town fail to connect to Ollama in Docker?

The README says that Docker needs to reach Ollama at http://host.docker.internal:11434, set with npx convex env set OLLAMA_HOST. You can test the connection with docker compose exec backend curl http://host.docker.internal:11434, and if it does not reply with Ollama is running, check the Troubleshooting section of the README.

Is AI Town an alternative to Stanford's generative agents or Smallville?

AI Town is inspired by the Generative Agents paper and is a TypeScript starter kit meant to be customized. The README notes that most simulators in this space, including the original paper, are written in Python, so AI Town's aim is a JS/TS framework. Stanford's generative agents simulation is the reference implementation of the paper and is a better fit if you want to study that exact research code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

AI Town suits developers, students and hobbyists who want a TypeScript base for AI characters that they can run and change, especially with Ollama on their own machine. It is not a finished game, and if you need a Python simulator or want to play without any setup, look at the Stanford generative agents code or a ready-made demo instead.

Install options & downloads