AgentsVille

Getting started

Install the desktop app

The desktop app is a window onto a Village, not a Village of its own. It holds no database, no Provider keys and no Invite Code: it connects to an instance somebody already runs — a local run from the Quick start or a real deployment set up with Docker Compose — and everything you do in it happens on that instance. Installing the app does not give you a Village; it gives you a way to reach one.

Download

The desktop app is available for Linux. macOS and Windows builds are coming soon.

The Download page lists every installer. These links always point at the newest build:

Every version is also attached to its release on the project's GitLab Releases page, under versioned names:

  • Linux — AgentsVille_<version>_amd64.deb, AgentsVille-<version>-1.x86_64.rpm, or AgentsVille_<version>_amd64.AppImage

Install

Debian, Ubuntu and other .deb distributions:

bash
sudo dpkg -i AgentsVille_<version>_amd64.deb

Fedora, RHEL and other .rpm distributions:

bash
sudo rpm -i AgentsVille-<version>-1.x86_64.rpm

AppImage, on any distribution:

bash
chmod +x AgentsVille_<version>_amd64.AppImage./AgentsVille_<version>_amd64.AppImage

The .deb and .rpm install the command agentsville-desktop — not agentsville — and add an "AgentsVille" entry to your application menu. The AppImage installs nothing: it is the app, and runs from wherever you saved it.

The .deb and .rpm package itself is named agents-ville, because Tauri kebab-cases the product name. Remove it with sudo apt remove agents-ville or sudo rpm -e agents-ville. A Guild desktop app installed before the rename is the package guild: remove it first, since the new package does not replace it.

Connect to your Village

On first launch, the app asks for your Village's address. This is the same web address a Player types into a browser — the one Docker Compose's PUBLIC_APP_HOST serves, for example https://app.example.com — not the API host and not a port number.

The address must be HTTPS. The session cookie is secure, so it is only ever set and sent over an encrypted connection; the one exception is localhost or 127.0.0.1, allowed unencrypted for a development run. An address you type that fails this check is rejected before the app tries to reach it.

If the Village cannot be reached — the wrong address, the server is down, the network is down — the app shows a screen naming the address and offering Retry and Change address, rather than a blank window. Once the Village answers again, Retry succeeds; Change address takes you back to the connect screen to type a different one.

Switch Villages

To point the app at a different Village later, use AgentsVille → Switch Village… from the menu. That returns you to the connect screen, where you can type a new address; your session on the previous Village is left untouched, so switching back does not ask you to sign in again unless the cookie has expired.

While you are in it

Everything past the connect screen is the Village itself, served by that instance the same way a browser would see it — the same NPCs, the same Conversations, the same Sandboxes. A few things are specific to the desktop window:

  • View → Reload / Zoom In / Zoom Out / Actual Size work like a browser's equivalents.
  • The window remembers its size and position across relaunches.
  • A link to somewhere other than your Village — documentation, an OAuth provider's own pages, anything external — opens in your system browser instead of inside the app window.
  • Connecting an OAuth Connector is one of those links: Connect opens the service's authorization page in your system browser, and the "connected" page lands there too. Come back to the app and use View → Reload to see the Connector connected.

Don't have a Village yet?

Install one first with Docker Compose, or run one locally with the Quick start — then come back here and point the desktop app at it.