AgentsVille

Self-hosting

Upgrading

AgentsVille upgrades by pulling the repository and rebuilding the images. Migrations are applied by the server itself on the way up.

The normal upgrade

bash
cd /srv/agentsville./scripts/backup.shgit pulldocker compose --profile caddy up -d --builddocker compose logs -f server

Keep whichever profiles you already run. If you use your own proxy, that is --profile none; if you run Sandboxes, add --profile sandbox.

Take the backup first. Migrations have no down step, so a migration you want to undo is undone by restoring a dump — see Backup and restore.

Upgrading from before AgentsVille

The release that renamed the product (ADR 0035) is a clean break. The database, volumes, containers, sandbox image and environment variables all change name, so the normal upgrade above would start an empty Village beside your old data. Follow "Upgrading to AgentsVille" in RUNBOOK.md instead, and take its backup before git pull.

What happens on start

The server's container command applies migrations and then starts listening:

pnpm --filter @agentsville/db db:migrate:deploy && node dist/index.mjs

Kysely's migrator applies anything the kysely_migration ledger does not already list, in name order, holding MySQL's GET_LOCK so two instances starting at once cannot both apply the same file.

A failed migration crashloops the container, deliberately. A server running against a stale schema is a worse outcome than a server that is down. If the stack comes up wrong after an upgrade, read docker compose logs server before assuming the problem is elsewhere.

Verify

bash
curl -f https://api.example.com/health

A healthy instance answers {"status":"ok","service":"agentsville"}. That endpoint runs SELECT 1, so it fails when the database is unreachable — unlike /, which answers OK without touching anything.

Then load the web app and send one Message. If the reply arrives all at once at the end rather than progressively, re-run pnpm sse:check against your API origin: an edge that stopped streaming is a silent failure.

Upgrading to the release that added Valkey

This release made VALKEY_URL required. The server refuses to boot without it, so add it to .env before you pull:

VALKEY_URL=redis://valkey:6379/0

Then upgrade as normal. docker compose up -d --build starts the valkey service alongside the others. Nothing else needs doing and no data has to be moved: rate limits, pending Connector authorizations and cached sessions all rebuild themselves.

It is required rather than optional on purpose. The rate limiter in front of SIGNUP_INVITE_CODE cannot silently degrade to per-process counting and still be the gate it claims to be.

Changing the API hostname

The API origin is compiled into the browser bundle at build time, so changing PUBLIC_API_URL is a rebuild rather than a restart:

bash
docker compose --profile caddy up -d --build web

The same applies to PUBLIC_APP_HOST and PUBLIC_API_HOST, which Caddy reads for its routing and its certificates. Check what Compose resolved before you rely on it:

bash
docker compose config | grep -E "PUBLIC_|VITE_"

Rolling back

There is no automatic path backwards. Migrations are hand-written and have no down, so a release that changed the schema cannot be reversed by checking out the previous commit.

To go back to a release that predates a migration:

  1. Stop the stack: docker compose stop server web.
  2. Restore the dump you took before the upgrade, following Backup and restore.
  3. Check out the previous tag or commit.
  4. docker compose up -d --build.

Anything a Player did between the backup and the rollback is lost. That is the cost of the ordering, and it is why the backup comes first.

Next