AgentsVille

Getting started

Quick start

This page takes a fresh checkout of the repository and gets a Village running on your own machine, at http://localhost:3000. It should take a few minutes.

If you are setting up an instance other people will use, read Install with Docker Compose instead — a local run is not a deployment.

Before you start

You need:

  • Node and pnpm. The repository pins its package manager in package.json, so corepack or a matching pnpm 11 install will do.
  • Docker, with the Compose plugin. MySQL and Valkey run as Compose services; the rest runs on your machine.
  • At least one Provider key — Anthropic, OpenAI, or both. The server refuses to start with neither.

Install the dependencies

AgentsVille is a pnpm monorepo. Install from the repository root:

bash
pnpm install

Create the .env

There is one .env in the repository, at the root, and every app and package reads that file and no other. Start from the example:

bash
cp .env.example .env

Most of the defaults already point at the local services. These are the ones you have to set yourself:

  • BETTER_AUTH_SECRET — at least 32 characters. Generate one with openssl rand -base64 48.
  • SIGNUP_INVITE_CODE — at least 16 characters. This is the Invite Code everyone presents to register, including you.
  • ANTHROPIC_API_KEY, OPENAI_API_KEY, both, or neither if every model runs locally (Using local models).

Leave DATABASE_URL, VALKEY_URL, BETTER_AUTH_URL, CORS_ORIGIN and VITE_SERVER_URL at their example values: they already describe a local run, with the API on port 8080 and the web app on port 3000.

A value already present in your shell always wins over the file, which is what lets Compose overrides take effect regardless of load order.

Start MySQL and Valkey

bash
pnpm db:startpnpm cache:start

Both publish on loopback only — MySQL on 127.0.0.1:3306, Valkey on 127.0.0.1:6379. Valkey is not optional: rate limits, pending Connector authorizations and cached sessions live there, and the server refuses to boot without VALKEY_URL.

Stop them again later with pnpm db:stop and pnpm cache:stop.

Apply the migrations

bash
pnpm db:migrate

This applies every migration the database has not already run. Run it again after pulling changes that add one.

Run it

bash
pnpm dev

That starts the web app and the API together. The web app is at http://localhost:3000 and the API at http://localhost:8080. To run only one of them, use pnpm dev:web or pnpm dev:server.

Register

Open http://localhost:3000 and create an account. You will be asked for an Invite Code: paste the value you put in SIGNUP_INVITE_CODE.

The first person to register on a fresh Village becomes the Operator. On your own machine that is you, which means you can also set the Village's default Provider and Model from the settings page.

If it does not start

  • The server exits naming a variable. Its configuration is validated at boot, so a missing or too-short value fails immediately rather than on the first Message. The message names the variable.
  • A Message is refused: "has no API key or address configured". The Provider it needs is not set up: set its key, or add a local Provider in Settings → Providers.
  • The migrations cannot connect. MySQL takes a few seconds to become healthy after pnpm db:start. Check with docker compose ps and run pnpm db:migrate again.

Next