# Installation

Run the browser locally, then connect it to an API and a persistent database for saved worlds and model decisions.

## Prerequisites

**Browser application**

Node.js 22 or newer and pnpm 10.7.1.

**API**

Python 3.11 and uv.

**Database**

PostgreSQL 18 with pgvector.

```text
git clone https://github.com/twinkling-reality/exulanica.git
cd exulanica
```

The browser, API, and workers are separate processes. The following commands run from the repository root unless a step changes directory.

## Start the Browser

```text
cd web
pnpm install --frozen-lockfile
pnpm app
```

Open the address printed by Vite. Adding ?preview=1 selects the read-only development fixture. The fixture also needs its locally supplied source images; a clean checkout alone does not establish a complete preview.

For saved worlds and live models, continue with the API setup and open the application without ?preview=1.

## Create a Persistent Database

```text
uv sync --extra reconstruction --extra segmentation --extra pose --extra server
```

Initialize a personal database in an empty, durable directory. The command creates, migrates, and starts the database on loopback, then prints connection URLs for its roles.

```text
uv run exulanica-local-db init --directory ~/Exulanica/database
uv run exulanica-local-db status --directory ~/Exulanica/database
```

Keep the printed URLs, including their passfile parameters. Use the owner connection to publish catalogs, then the exulanica_app connection to run the API. Do not run the API with the owner role.

```text
EXULANICA_DATABASE_URL="<owner connection URL>" \
EXULANICA_DATA_DIR="$HOME/Exulanica/content" \
  uv run exulanica-character-catalog publish --apply
```

## Configure and Start the API

Create a long random token and two UUIDs for a workspace and actor. Replace every angle-bracket placeholder below. Keep the token private; it grants access to the named workspace.

```text
export EXULANICA_DATABASE_URL="<exulanica_app connection URL>"
export EXULANICA_DATA_DIR="$HOME/Exulanica/content"
export EXULANICA_API_TOKENS='{"<random token>":{"workspace_id":"<workspace UUID>","actor":"<actor UUID>","permissions":["library.read","library.write","world.read","world.write","model.invoke"]}}'
uv run uvicorn --factory exulanica.api.app:create_app --port 8000
```

The development browser proxies API requests to http://127.0.0.1:8000. Set EXULANICA_API_URL when starting the browser if your API uses another address. On an installation without browser accounts, use its developer-token entry.

Check /readyz before using the installation. It reports missing configuration and unpublished catalogs. A running HTTP server does not establish that every optional capability is ready.

## Enable Models and Playback

Model calls require a provider credential, an allowed provider origin, and a spending mode. The following is a local process-budget configuration. Set your own budget before restarting the API with these variables.

```text
export NEBIUS_API_KEY="<your provider key>"
export EXULANICA_EGRESS_ALLOWLIST='["https://api.tokenfactory.nebius.com"]'
export EXULANICA_SPENDING=process
export EXULANICA_BUDGET_USD="<your budget in USD>"
export EXULANICA_SOCIETY_CONTROL_WORKSPACES='["<workspace UUID>"]'
```

EXULANICA_SOCIETY_CONTROL_WORKSPACES is a JSON array of workspace ids. A bare id is refused at startup, and no society in that workspace is played. A process budget resets when the process restarts. Hosted installations should configure the shared durable spending authority. Without a provider, people can follow routines but model-dependent operations remain unavailable.

Once configured, follow [Choose a model](/docs/models#docs-models-models) in Models and decisions.

## Prepare the Services Your World Needs

**Saved catalog worlds**

Persistent database, content store and published catalogs.

**Generated towns**

Generated-tile preparation worker and its configured build inputs. A saved town waits until its tiles are baked.

**Live people and comparisons**

Playback for the workspace, comparison execution and configured model/spending services.

**Your own 3D assets**

Workspace asset preparation worker. Admitted content waits until a compatible preparer runs.

**Reconstructed places**

Source admission and the reconstruction services appropriate to the input.

The commands above establish a local API foundation. Select and configure the workers for your workflow before expecting every creation path to run. Read /readyz and the world’s capability refusals to identify missing services.

[Service topology, worker configuration and deployment profiles](https://github.com/twinkling-reality/exulanica/blob/main/docs/deployment.md)
## Maintenance

```text
uv run exulanica-local-db backup --directory ~/Exulanica/database
uv run exulanica-local-db verify --directory ~/Exulanica/database
```

Database backups do not include EXULANICA_DATA_DIR. Back up the content directory too, and keep copies on another disk. Use exulanica-local-db upgrade for this managed database; it backs up and rehearses the migration before applying it.

Use [Database restore and upgrade](https://github.com/twinkling-reality/exulanica/blob/main/docs/local-database.md) for the managed database’s recovery procedures.

Google browser sign-in requires HTTPS, registered callback and return URLs, permitted browser origins, and a separate account database role. Do not expose this local token-based setup as a public sign-in service.