AgentsVille

Getting started

Connecting to a Village

A Village is a server you run — on your own machine, on a box on your network, or in the cloud — and the apps are windows onto it. The web UI and the desktop app both connect to a Village by its address, and both can switch between several.

From the desktop app

On first launch the app asks for your Village's address and opens it. AgentsVille → Switch Village… in the menu goes back to that screen, so one app can reach a Village on this machine and another in the cloud. See Install the desktop app.

From a web browser

A Village you deploy serves its own web UI, already pointed at its own server: open it and sign in.

Any AgentsVille web UI can also connect to a different Village — a hosted one such as the public site, or your own UI reaching a second server:

  1. On the sign-in page, choose Change next to the server address (or open the menu under your name and choose Switch Village server).
  2. Enter the Village's API address — https://api.agentsville.example in the cloud, or http://localhost:8080 on this machine. Plain http is accepted only for localhost and 127.0.0.1, where the traffic never leaves the machine.
  3. The page checks that a Village answers there, then asks you to sign in.

The Villages you have used are listed on the same screen, so switching back is one click. They are remembered in this browser only.

What the Village has to allow

A browser only lets a page on one site talk to a server on another if the server says so. The Village you connect to must list the web UI's origin in CORS_ORIGIN, which takes a comma-separated list:

ini
CORS_ORIGIN=https://app.example.com,https://agentsville.codebrewerz.com

Restart the server after changing it. If connecting fails with "No Village answered", this list is the first thing to check.

If it says the server runs an older version (Guild), that server predates the rename to AgentsVille and is refused: upgrade it following Upgrading.

How you stay signed in

  • The Village that served the page keeps you signed in with an httpOnly cookie, which no script on the page can read.
  • Any other Village signs you in with a bearer token, kept in this browser's storage for that server and sent with every request. Browsers increasingly refuse the cross-site cookie the first way would need.

The token is removed when you sign out or forget the server. The trade-off is stated in ADR 0027: a script injected into the page could read a token, where it could not read the cookie.

Where to go next