Reference

Environment variables

Every variable AgentsVille reads, what sets it, and what happens when it is absent. For the order to set them in and why, read Configuration; this page is the lookup.

There is one .env in the repository, at the root. Every app and package reads that file and no other. Node loads it natively — nothing here depends on the dotenv package — and a variable already present in the environment always wins over a line in the file. .env.example is the annotated template.

An empty string counts as unset. A variable set to "" falls back to its default rather than being read as an empty value.

API server

Validated at boot. A missing or malformed required variable stops the process rather than letting it serve a half-configured instance.

Variable	Required	Default	What it does
`DATABASE_URL`	Yes	—	MySQL connection URL, `mysql://user:password@host:3306/agentsville`. Also the one variable the migration runner reads.
`VALKEY_URL`	Yes	—	Valkey connection URL. Rate limits, pending Connector authorizations and cached settings live here. Required rather than optional: a limiter that silently falls back to per-process counting is not the control it claims to be.
`BETTER_AUTH_SECRET`	Yes	—	Signs sessions. At least 32 characters. Changing it signs every Player out.
`BETTER_AUTH_URL`	Yes	—	The API's own public URL. Must be a URL.
`CORS_ORIGIN`	Yes	—	Web origins allowed to use the API, comma-separated: the Village's own web app and any hosted AgentsVille UI its Players connect from. Each must be a URL.
`SIGNUP_INVITE_CODE`	Yes	—	The Invite Code every new Player must present to register. At least 16 characters. Kept as one row, `env`, among the Operator's invite codes: without a limit until the Operator sets one, never deletable, turned off by a limit of 0. Rotated by changing it and restarting.
`ANTHROPIC_API_KEY`	No	—	Key for the built-in Anthropic Provider. A key saved in Settings replaces it.
`OPENAI_API_KEY`	No	—	Key for the built-in OpenAI Provider. Memory embeddings use it only when no embedding model is chosen in Settings.
`NODE_ENV`	No	`development`	One of `development`, `production`, `test`. In `development` the database logs every query.
`PORT`	No	`8080`	The port the API listens on.
`LOG_DRAIN`	No	empty	Comma-separated evlog adapter names. Empty means stdout in production and `.evlog/logs` in development. Known adapters: `axiom`, `better-stack`, `clickhouse`, `datadog`, `fs`, `hyperdx`, `loki`, `memory`, `otlp`, `posthog`, `sentry`. Each reads its own credentials, so adding a destination never means editing the schema.
`TRUSTED_PROXIES`	No	`true`	Which upstreams may set `X-Forwarded-For`. `true` trusts the immediate hop, correct behind the bundled edge. A comma-separated list of addresses or CIDRs narrows it. `false` ignores the header. Rate limits are keyed on the client address, so trusting an upstream anyone can reach hands out a fresh identity per request.
`SANDBOX_BROKER_URL`	No	empty	Where the sandbox broker listens. Unset with `SANDBOX_BROKER_TOKEN` means Sandboxes are off and the Tools say so.
`SANDBOX_HOST_MOUNT_ROOTS`	No	empty	Host folders the Operator may lend to Sandboxes, comma-separated. Read by the server (to show and pre-check) and the broker (which enforces it). Empty means Host Mounts are off.
`SANDBOX_BROKER_TOKEN`	No	empty	Bearer token for the broker. Both this and the URL must be non-empty for Sandboxes to work.
`PUBLIC_API_URL`	No	empty	Where a Player's browser is sent back after authorising a Connector. Empty means the API's own origin, which is right for the bundled deployment.
`CONNECTOR_OAUTH_PREFIX`	No	`CONNECTOR_`	The prefix the per-service OAuth variables are looked up under.
`SKIP_ENV_VALIDATION`	No	unset	Any non-empty value skips validation entirely. For builds and tests, not for running an instance.

Neither Provider key is required. A Village can run entirely on Providers added in Settings → Providers — a model on the Operator's own machine needs no key at all — so there is nothing to check at boot. A Village with no usable model refuses each Message with NO_MODEL_CONFIGURED or PROVIDER_NOT_CONFIGURED, and Settings shows which Providers are ready.

Connector OAuth clients

Read dynamically, one pair per service, so adding a service to the catalogue needs no schema change. The names are the CONNECTOR_OAUTH_PREFIX followed by the kind in upper case:

Variable	Required	Default	What it does
`CONNECTOR_LINEAR_CLIENT_ID`	No	unset	OAuth client id for Linear.
`CONNECTOR_LINEAR_CLIENT_SECRET`	No	unset	OAuth client secret for Linear.
`CONNECTOR_NOTION_CLIENT_ID`	No	unset	OAuth client id for Notion.
`CONNECTOR_NOTION_CLIENT_SECRET`	No	unset	OAuth client secret for Notion.
`CONNECTOR_ATLASSIAN_CLIENT_ID`	No	unset	OAuth client id for Jira and Confluence.
`CONNECTOR_ATLASSIAN_CLIENT_SECRET`	No	unset	OAuth client secret for Jira and Confluence.

A service whose pair is unset is offered in the catalogue as unavailable rather than hidden, so a Player can ask their Operator for it. The other catalogue entries — Composio and Sentry — take a token the Player pastes in and need no variables here.

Each service's redirect URI is PUBLIC_API_URL plus /api/connectors/<kind>/callback. See Connecting Linear, Notion and Jira.

Web app

Variable	Required	Default	What it does
`VITE_SERVER_URL`	No, build time	—	The web app's default Village server, baked in when the bundle is built. Unset, the web app asks which Village to connect to; either way a Player can switch servers at runtime (Connecting to a Village).
`VITE_SITE_URL`	No, build time	unset	The public site's own origin. Set only on the public AgentsVille site: it turns on canonical links, `sitemap.xml` and indexing. Unset, every page carries `noindex` and `robots.txt` disallows crawling.
`SERVER_URL`	No	unset	Where the web app resolves sessions during server-side rendering. Compose sets it to the compose-network address so rendering never hairpins through public DNS and the TLS edge. Leave unset for local development.
`NODE_ENV`	No	`development`	Standard. Compose sets `production`.
`PORT`	No	`3000`	Set by Compose.
`LOG_DRAIN`	No	empty	As above; the web app ships its own events.

Sandbox broker

Only used with docker compose --profile sandbox, which runs the one service that holds the Docker socket. Read The sandbox boundary before enabling it.

Variable	Required	Default	What it does
`SANDBOX_BROKER_TOKEN`	Yes	—	The bearer token the API server must present. At least 16 characters, or the broker refuses to start. Generate one with `openssl rand -base64 24`.
`SANDBOX_IDLE_MINUTES`	No	`30`	How long a Sandbox may sit unused before it is stopped. Stopped, not destroyed: the container and its volume both survive. The sweep runs every quarter of this interval, and no more often than once a minute.
`PORT`	No	`8008`	The port the broker listens on. It publishes no ports outside the Compose network.

These are read by the Docker driver inside the broker:

Variable	Required	Default	What it does
`AGENTSVILLE_SANDBOX_IMAGE`	No	`agentsville-sandbox:latest`	The image a Sandbox runs. Built by `pnpm sandbox:build`.
`AGENTSVILLE_SANDBOX_NETWORK`	No	`agentsville_sandbox_net`	The internal network a Sandbox joins when it has no egress. Compose sets it explicitly.
`AGENTSVILLE_SANDBOX_EGRESS_NETWORK`	No	`bridge`	The network a Sandbox joins when the Operator has granted egress.

Read by Docker Compose only

These never reach the application. They are substituted into docker-compose.yml itself.

Variable	Required	Default	What it does
`MYSQL_PASSWORD`	No	`password`	The `user` account's password, and the password in the `DATABASE_URL` Compose builds for the server. A public deployment must set a real one.
`MYSQL_ROOT_PASSWORD`	No	`password`	The MySQL root password. Also read by `scripts/backup.sh`.
`PUBLIC_APP_HOST`	No	`app.localhost`	The hostname the reverse proxy serves the web app on.
`PUBLIC_API_HOST`	No	`api.localhost`	The hostname the reverse proxy serves the API on.
`PUBLIC_API_URL`	No	`http://localhost:8080`	Doubles as the `VITE_SERVER_URL` build argument for the web image. The application reads this variable too, for a different purpose — see the server table above.
`SANDBOX_BROKER_URL`	No	`http://sandbox-broker:8008`	Passed to the server. Set to nothing to leave Sandboxes off while the profile is running.
`TRUSTED_PROXIES`	No	`true`	Passed to the server.
`LOG_DRAIN`	No	empty	Passed to the web app.

Compose also sets NODE_ENV, PORT, DATABASE_URL, VALKEY_URL and SERVER_URL for its services from fixed values, overriding whatever .env says for those keys.

Read by the backup script

scripts/backup.sh reads four of its own. They are documented with the script, in Scripts.