Installation¶

Lumiverse runs on your own machine. It needs Bun (a fast JavaScript runtime) and takes about two minutes to set up.

Requirements¶

• Bun v1.1 or later — Install Bun (the start scripts auto-install Bun if it's missing)
• A modern web browser (Chrome, Firefox, Edge, Safari)
• An API key from at least one AI provider (OpenAI, Anthropic, Google, etc.)

Install & Run¶

1. Clone the repository¶

git clone https://github.com/prolix-oc/Lumiverse.git
cd Lumiverse

2. Start the server¶

chmod +x start.sh
./start.sh

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

.\start.ps1

chmod +x start.sh
./start.sh

The start script handles everything: auto-installs Bun if needed, runs bun install, triggers the setup wizard on first launch, and starts the server.

3. Open in your browser¶

Navigate to http://localhost:7860. On first launch, the setup wizard guides you through account creation.

First-Run Setup Wizard¶

The setup wizard runs automatically on first launch. It walks through four steps:

1. Admin Account — Set a username (default: admin) and password (minimum 8 characters)
2. Server Port — Choose a port (default: 7860)
3. Extension Storage — Set the maximum storage for extensions (default: 500 MB)
4. Identity Generation — Creates data/lumiverse.identity (your encryption key) and data/owner.credentials

You can also run the wizard manually:

./start.sh --setup

Start Script Options¶

The start scripts accept flags to control behavior:

Docker¶

Lumiverse provides pre-built Docker images for the simplest possible deployment.

Available Image Tags¶

Pre-built images are published to GitHub Container Registry under ghcr.io/prolix-oc/lumiverse:

Switching between tags is just a matter of editing the image: line in docker-compose.yml and running docker-compose pull && docker-compose up -d. Your lumiverse-data volume is untouched, so your database and settings carry over between tags.

Quick Start (Pre-Built Image)¶

docker-compose up -d

Edit docker-compose.yml to set your owner password and any other configuration. Any supported application .env value can also be passed here through Docker environment: entries:

services:
  lumiverse:
    image: ghcr.io/prolix-oc/lumiverse:latest
    container_name: lumiverse
    ports:
      - "7860:7860"
    environment:
      - OWNER_PASSWORD=changeme123    # Required — minimum 8 characters
      - OWNER_USERNAME=admin          # Optional
      - PORT=7860
      - TRUST_ANY_ORIGIN=true

      # Optional app-level env values
      # - DATA_DIR=/app/data
      # - AUTH_SECRET=
      # - ENCRYPTION_KEY=
      # - SPINDLE_EPHEMERAL_GLOBAL_MAX_BYTES=524288000
      # - SPINDLE_EPHEMERAL_EXTENSION_DEFAULT_MAX_BYTES=52428800
      # - SPINDLE_EPHEMERAL_EXTENSION_MAX_OVERRIDES=example.extension:104857600
      # - SPINDLE_EPHEMERAL_RESERVATION_TTL_MS=600000

      # Optional one-time SillyTavern migration
      # - LUMIVERSE_ST_MIGRATE=true
      # - SILLYTAVERN_PATH=/app/data/SillyTavern
      # - SILLYTAVERN_TARGET_USER=default-user
      # - SILLYTAVERN_MIGRATION_TARGET=5
      # - LUMIVERSE_FORCE_NEW_MIGRATION=false
    volumes:
      - lumiverse-data:/app/data
      # - /path/to/SillyTavern:/app/data/SillyTavern:ro
    restart: unless-stopped

volumes:
  lumiverse-data:

Build from Source¶

If you want to build the image locally:

docker-compose -f docker-compose.build.yml up -d

Forcing a fresh frontend bundle¶

The build pipeline uses Docker's layer cache, so if Docker doesn't see a meaningful change in the frontend inputs it will reuse the previously baked Vite bundle. This is normally what you want — but if you're tracking the staging branch (or anywhere else fast-moving), you may want to guarantee the bundle was rebuilt from your current checkout before it gets packaged into the image.

The build accepts a FRONTEND_REFRESH build arg that cache-busts the Vite build layer without invalidating apt, the CA refresh, or backend dependencies:

FRONTEND_REFRESH=$(date -u +%s) docker compose -f docker-compose.build.yml build
docker compose -f docker-compose.build.yml up -d

$env:FRONTEND_REFRESH = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
docker compose -f docker-compose.build.yml build
docker compose -f docker-compose.build.yml up -d

Any value different from the last build will do — the timestamp examples above are just an easy way to guarantee uniqueness.

CA_REFRESH=$(date -u +%G-W%V) FRONTEND_REFRESH=$(date -u +%s) \
  docker compose -f docker-compose.build.yml build

If you'd rather throw away the cache entirely (slower, but belt-and-braces), pass --no-cache to docker compose build instead.

Docker Environment Variables¶

Docker SillyTavern Migration¶

If you are moving from an existing SillyTavern install, Lumiverse can perform a one-time import automatically when the container starts.

services:
  lumiverse:
    environment:
      - OWNER_PASSWORD=changeme123
      - LUMIVERSE_ST_MIGRATE=true
      - SILLYTAVERN_PATH=/app/data/SillyTavern
      - SILLYTAVERN_TARGET_USER=default-user
      - SILLYTAVERN_MIGRATION_TARGET=5
    volumes:
      - lumiverse-data:/app/data
      - /path/to/SillyTavern:/app/data/SillyTavern:ro

• Use a read-only bind mount for the SillyTavern folder. Lumiverse only reads from it and does not modify the source data.
• The importer supports both newer SillyTavern layouts (data/<user>/) and older installs that still use public/.
• SILLYTAVERN_MIGRATION_TARGET controls what gets imported:
  • 1 = characters only
  • 2 = world books only
  • 3 = personas only
  • 4 = characters and chat history (including group chats)
  • 5 = everything
• Migration state is saved after a successful run, so later container restarts skip it automatically.
• Set LUMIVERSE_FORCE_NEW_MIGRATION=true only when you intentionally want to run the import again.

Data Persistence¶

The Docker setup uses a named volume (lumiverse-data) mounted at /app/data. This persists your database, encryption key, credentials, uploaded images, and extensions across container restarts.

Configuration¶

Lumiverse uses a .env file for runtime configuration (created by the setup wizard). Common options:

API keys and account passwords are stored encrypted in the data/ directory rather than in .env. Leave AUTH_SECRET and ENCRYPTION_KEY unset unless you are intentionally carrying forward an existing install.

Updating¶

The easiest way to update Lumiverse is from the Operator Panel in the running app — no terminal interaction needed.

From the Operator Panel (recommended)¶

1. Open Settings → Operator Panel.
2. Click Check for Updates. The panel reports how many commits behind you are and previews the latest commit message.
3. If an update is available, click Apply Update. Lumiverse pulls the latest code, reinstalls dependencies, rebuilds the frontend, and restarts the server. Your browser reconnects automatically when the new build is ready.

The runner that the start scripts launch is what carries out the update on your behalf. It needs to be attached for the Operator Panel buttons to work — the panel shows Runner IPC: Connected when it is. If the badge reads Unavailable (e.g. you launched with --no-runner / -NoRunner, or restarted the backend outside the runner), use the command-line flow below instead.

From the Command Line¶

git pull
./start.sh --build

git pull
.\start.ps1 -Build

docker-compose pull
docker-compose up -d

The --build / -Build flag rebuilds the frontend before launching — important on a fresh pull because the precompiled assets won't match the new source.

Database migrations run automatically on startup — your data is preserved across updates.

Switching Branches¶

Lumiverse ships two long-lived branches:

You can move between branches at any time. Your data/ folder is unaffected.

From the Operator Panel (recommended)¶

If you launched Lumiverse with one of the start scripts, the runner is attached by default and you can switch branches without leaving the app:

1. Open Settings → Operator Panel.
2. Look at the Branch card — it shows the branch you're on (main or staging).
3. Click Switch to staging (or Switch to main if you're already on staging).
4. Confirm the prompt. Lumiverse will checkout, pull, reinstall, rebuild the frontend, and restart the server. Your browser will reconnect automatically when the new build is up.

From the Command Line¶

git fetch origin
git checkout staging      # or: git checkout main
git pull
./start.sh --build

git fetch origin
git checkout staging      # or: git checkout main
git pull
.\start.ps1 -Build

The --build / -Build flag rebuilds the frontend before launching — important when switching branches because the precompiled assets differ.

Migrating from SillyTavern¶

If you're coming from SillyTavern, Lumiverse includes a migration tool that imports your characters, chat history, world books, and personas. You can migrate from a local directory, or connect to a remote machine over SFTP or SMB if your SillyTavern installation lives on another device.

Running the Migration¶

There are two ways to run the migration:

Web UI (recommended)¶

Open Lumiverse, go to Settings > Migration, and follow the wizard. This is the easiest approach and supports all three connection methods (Local, SFTP, SMB).

CLI¶

./start.sh --migrate-st

.\start.ps1 -MigrateST

bun run migrate:st

Connection Methods¶

The web migration wizard lets you choose how to access your SillyTavern data:

Local¶

Browse directories on the machine running Lumiverse. This is the default and requires no extra setup.

SFTP (SSH File Transfer)¶

Connect to a remote machine over SSH. Useful when SillyTavern is on a VPS, home server, or any machine you can SSH into.

• Authentication: Password or private key (upload a .pem/.key file or paste it directly)
• Requirements: An SSH server running on the remote machine (standard on Linux/macOS)

SMB (Samba / Windows Shares)¶

Connect to a network share. Useful when SillyTavern data is on a NAS (Synology, TrueNAS, QNAP, etc.), a Windows PC, or any Samba share.

• Authentication: Username/password, with optional domain
• Requirements: The smbclient package must be installed on the machine running Lumiverse

Installing smbclient¶

sudo apt install smbclient

sudo dnf install samba-client

sudo pacman -S smbclient

sudo apk add samba-client

brew install samba

pkg install samba

Migration Walkthrough¶

The web UI wizard walks you through these steps:

1. Choose connection — Select Local, SFTP, or SMB and enter credentials if needed. For remote connections, click Test Connection to verify before proceeding.
2. Browse & validate — Navigate to your SillyTavern root directory (the folder containing the data/ subfolder) and click Validate.
3. Select ST user — If your SillyTavern has multiple user profiles, choose which one to migrate.
4. Select scope — Choose what to import:
   • Characters only
   • World Books only
   • Personas only
   • Characters + Chat History (including group chats)
   • Everything (recommended)
   • Custom selection
5. Select target — Choose which Lumiverse account receives the data.
6. (Optional) TagLibrary Backup — If you used the SillyTavern-TagLibrary extension and exported a JSON backup, upload it here. Lumiverse will re-apply your tags to the imported characters once the main migration finishes. See TagLibrary Re-Apply below.
7. Confirm & import — Review the summary and start the migration. Progress and logs stream in real time.
8. Results — See counts of imported, skipped, and failed items.

TagLibrary Re-Apply¶

The standalone TagLibrary extension for SillyTavern stores its character tags outside the character card itself, so they are not part of a normal SillyTavern export. Lumiverse can pull them back in:

1. In SillyTavern, open the TagLibrary extension and export your backup as JSON
2. On the Confirm step of the Migration wizard, expand Optional: TagLibrary Backup and upload the JSON file
3. After the main migration completes, Lumiverse automatically runs the TagLibrary import and matches tags to imported characters using their source filenames and original image filenames

A toast reports the results — how many tags were applied, how many were skipped because no matching character was found, and how many failed to parse. Existing character tags are preserved; the import only adds tags, it never removes them.

What Gets Imported¶

Next Steps¶

Once Lumiverse is running, head to First Steps to connect your first AI provider and start chatting.