🛠️Install

Installation

The overall steps are:

1. Build and Deploy

2. Connect it to an LLM

Build and Deploy

There are a few ways to run the app on top of Convex (the backend).

• Standard Convex Setup: Develop locally or in the cloud. Requires a Convex account (free).

• Docker Compose: Try it without an account.

• Community Fork: One-click install on Pinokio.

• Fly.io Deployment: See ./fly for instructions.

Standard Setup

If you're on Windows, see below.

git clone https://github.com/AITownFun/ai-town.git
cd ai-town
npm install

To run it:

npm run dev

Visit http://localhost:5173.

To run frontend and backend separately:

npm run dev:frontend
npm run dev:backend

Using Docker Compose with Self-Hosted Convex

docker compose up --build -d

After setup:

• Frontend: http://localhost:5173

• Backend: http://localhost:3210

• Dashboard: http://localhost:6791

Generate admin key:

docker compose exec backend ./generate_admin_key.sh

Add to .env.local:

CONVEX_SELF_HOSTED_ADMIN_KEY="<admin-key>"
CONVEX_SELF_HOSTED_URL="http://127.0.0.1:3210"

Set up the Convex backend:

npm run predev

Connect an LLM

• Ollama (default): Run it locally.

• OpenAI: Set OPENAI_API_KEY.

• Together.ai: Set TOGETHER_API_KEY.

• Other OpenAI-Compatible APIs: Configure LLM_API_URL, LLM_API_KEY, LLM_MODEL, etc.

Note: If you change the LLM provider or embedding model, delete your data and start over.