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.

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

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¶

git pull
./start.sh

git pull
.\start.ps1

docker-compose pull
docker-compose up -d

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

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. Confirm & import — Review the summary and start the migration. Progress and logs stream in real time.
7. Results — See counts of imported, skipped, and failed items.

What Gets Imported¶

Next Steps¶

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