Install

Runs on Linux, macOS and Windows. Each one is tested with a fresh install on a clean machine.

Orbweaver runs on your own computer and you open it in your browser. There are two ways to run it: Docker, or straight from the source with pnpm. Pick one. Both serve it at http://localhost:8788 unless you choose another port.

What you need

• A computer to run it on. Linux, macOS and Windows all work. Orbweaver doesn't run the language model itself, so you don't need a graphics card. You point it at a model you pay for, or at a model server you already run (see Connect a model).
• Git, to download the code.
• Docker (with the Compose plugin) or Podman for the Docker path, or pnpm for the from-source path. You don't install Node yourself: pnpm fetches the right version on its own.
• An internet connection for the first start. It downloads the app's dependencies, and then a search model in the background (below).

The first-run download

Orbweaver has a small search model built in. It's what lets you find characters and old scenes by meaning instead of by exact words, and it feeds long-chat memory. The first time you start, Orbweaver downloads it in the background just after the app is up:

• About 1 GB in total: the search model is about 874 MB, and the default Ettin reranker 32M downloads about 37 MB including its tokenizer and configuration.
• The search model uses about 2 GB of RAM once loaded. The reranker adds about 150 MB while idle and can use roughly another 0.6 GB while scoring at its 2,048-token window. Both run on the CPU, so they don't touch your graphics card.
• It doesn't hold up the start. You can open the app and look around while it downloads. If you search before it finishes, the search waits for the download.
• It lands in the cache folder inside your data folder (see Where your data lives), and it only downloads once.
• If you already point search at a model server of your own, nothing is downloaded for it.

Built-in reranking adds time, not API charges. On the measured four-core x64 setup, typical turns took about 0.4–2.6 seconds; eight long memory passages took about 6 seconds. These are examples, not a latency guarantee. Under Model roles, a built-in Ettin reranker 17M is the lighter option; MiniLM reranker is faster but reads only 512 tokens per pair. The default Ettin reads up to 2,048.

On a metered or offline connection, set LOCAL_LIGHT_PREFETCH=off in your settings file. Nothing downloads until a feature first asks for it, and that first request pays the whole wait. For Docker the settings file is docker/orbweaver.local.env, which you create by copying docker/orbweaver.local.env.example. For a source install it's .env in the Orbweaver folder, which the first pnpm start creates (see First start questions).

The quick way

One command installs Git and pnpm if they're missing, downloads the stable release, asks whether you want Docker or from source, and starts it.

On Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/Inktomi93/OrbWeaver/release/install.sh | bash

On Windows, download install.cmd and double-click it. It installs Git and pnpm with winget when they're missing, and puts Orbweaver in an OrbWeaver folder in your user folder.

Afterwards, the Orbweaver folder has three scripts for every day:

Script	What it does
start.sh / start.cmd	Starts Orbweaver. Anything you add after it goes to pnpm start, so ./start.sh --setup asks the first start questions again and ./start.sh --share starts a shared session.
update.sh / update.cmd	Updates to the newest version and starts it again. See Updating.
install.sh / install.cmd	The installer itself. You only need it once.

The two options below are the same steps by hand.

Option 1: Docker

This works the same on Linux, macOS and Windows.

git clone https://github.com/Inktomi93/orbweaver
cd orbweaver
docker compose -f docker-compose.yaml -f docker/compose.build.yaml up -d --build

Open http://localhost:8788. There is no login: the app only listens on this machine, and you are the owner.

• This path builds from your checkout. The build overlay selects the Dockerfile and a local image, so the first run takes a few minutes. Keep the same overlay when updating or recreating the container; the base Compose file alone selects the release image instead.
• Settings that aren't in the app go in docker/orbweaver.local.env. Copy docker/orbweaver.local.env.example to that name to create it. Everything in there is optional.
• A model server on the same machine (Ollama, KoboldCpp, LM Studio and the like) is not at localhost from inside the container. It's at host.docker.internal, and the owner has to admit that name as a private address. Connect a model walks through it.
• Letting other people in takes three lines in docker/orbweaver.local.env and a docker compose -f docker-compose.yaml -f docker/compose.build.yaml up -d. The questions that a source install asks (below) don't apply to a container. Who can sign in, under Settings, Admin, Multi-user, shows your current sign-in mode and the exact lines to change it. See Share with friends.

Option 2: From source

1. Install Git and pnpm

On Linux and macOS:

curl -fsSL https://get.pnpm.io/install.sh | sh -

On Windows, in PowerShell:

Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

If Windows Defender blocks the pnpm download, run winget install -e --id pnpm.pnpm instead.

2. Download and start

git clone https://github.com/Inktomi93/orbweaver
cd orbweaver
pnpm install
pnpm start

Or run ./start.sh (Linux, macOS) or start.cmd (Windows), which do the same with a few checks first.

The first pnpm start builds the app's front end, which takes a little while, then runs the server in that terminal and opens Orbweaver in your default browser once it answers. Press Ctrl-C in the terminal to stop it.

If you'd rather it didn't open a browser, set OPEN_BROWSER=off in .env. It also stays closed when you're connected over SSH.

First start questions

The first time you run pnpm start in a terminal, it asks a few things and saves your answers to a .env file in the Orbweaver folder. It only asks when there is no .env yet, so if you create one yourself first, you skip the questions. Press Enter to keep the value in brackets. Ctrl-C at any point stops without saving anything.

It asks	What it means
Port	Where Orbweaver listens. The default is 8788.
Who will use Orbweaver?	Just me, on this computer (no sign-in, the default), or me and friends (everyone signs in).
How will people sign in?	Only asked for "me and friends". A password stored by Orbweaver, or single sign-on through your identity provider. Single sign-on needs settings that the questions don't collect, so until you add them people sign in with a password.
Any other name people will type to reach this?	Only asked for "me and friends". It shows the addresses other devices can open. An IP address needs no entry.

Choosing "just me" means no login at all, and other devices on your network can't connect. Right answer if you're the only one using it. Choosing "me and friends" ends with a summary of what was saved and the addresses other devices can open. With password sign-in it also names the next step for friends outside your network: sign in as the owner and press Start sharing under Settings, Admin, Multi-user. → Share with friends

To change your answer later, run pnpm start --setup (or ./start.sh --setup, start.cmd --setup). To try a different port for one run without saving it, use pnpm start --port 9000.

The questions only appear when someone is at the keyboard. Started from a service, a script or a pipe, pnpm start asks nothing and runs on the defaults.

On Windows

• After pnpm install, you can double-click start.cmd in the Orbweaver folder instead of typing pnpm start. It opens its own console window, asks the first start questions there, and keeps the window open if the start fails so you can read why.
• In a terminal, use PowerShell or Windows Terminal. Git Bash's own terminal doesn't look like a keyboard to the app, so it skips the questions and starts on the defaults.
• Under WSL2, other devices can't reach the app until you turn on mirrored networking in WSL (Windows 11) or forward the port from Windows. You only need this if you want to open Orbweaver from your phone or another computer.
• Plugins run in a separate sandbox process. Its containment and supervision are proven by the install CI on Linux, macOS and Windows.

Where your data lives

Everything Orbweaver keeps is in one data folder: your characters, chats, settings, uploaded images, and your saved provider keys.

Install	Where the data is
Docker	A Docker volume called orbweaver-data. docker volume ls lists it as orbweaver_orbweaver-data.
From source	The data folder inside the Orbweaver folder.

Two files in its secrets folder matter more than the rest. One decrypts your saved provider keys, and the other is what passwords and sign-ins are checked against. A copy of your database without them can't read its keys or sign anyone in, so keep them with any backup. The cache folder holds things Orbweaver can download or build again, like the search model, so you can leave it out of a backup. Back up and restore has the full steps.

Updating

Orbweaver updates by pulling the latest code and starting again. Your data stays where it is.

The easy way: run ./update.sh in the Orbweaver folder, or double-click update.cmd on Windows. It works for both kinds of install.

• From source, if Orbweaver is running, it asks you to stop it in its own window (Ctrl-C, or close the window) and waits. Orbweaver finishes what it's doing and closes its database before it stops, so nothing is cut off mid-write. Then it downloads the update, installs it and starts Orbweaver again. ./update.sh --no-start updates without starting.
• In Docker, it pulls the new image (or rebuilds yours, if you built it from the checkout) and restarts the container. Docker gives the app 30 seconds to finish before it stops it.
• It refuses to touch a checkout where you've changed files, and says which ones, so an update never overwrites your edits.

By hand, Docker:

git pull
docker compose -f docker-compose.yaml -f docker/compose.build.yaml up -d --build

By hand, from source: stop the app, then:

git pull
pnpm install
pnpm start

pnpm start rebuilds the front end by itself when the code has changed.

Before a start that changes your database, Orbweaver copies it into the backups folder inside your data folder, and then updates it. Updates only go forward. If you ever need to go back to an older version, you restore that copy by hand, so make a full backup first before a big update.

To see which version you're running, open Settings and go to This install. Anyone with an account can read it there and copy it for a bug report. The owner and admins also get Check for updates on the same page, which asks whether a newer one exists. It only checks when you press the button.

Stopping

• From source: press Ctrl-C in the terminal, or close the window. Either way Orbweaver finishes what it's doing and closes its database first.
• Docker: docker compose stop stops the app and docker compose start starts the same container again. Docker also starts it back up after a reboot unless you've stopped it. docker compose down removes the container but keeps your data. Don't add -v to down unless you want your data gone: that deletes the volume.

Your first time in the app

The first time you open Orbweaver, it asks "Who are you in the story?" Give yourself a name, and optionally a short description of how characters should picture you. That's your persona, the character you play. You can change it any time under Personas in Settings.

Next steps

Orbweaver doesn't come with a language model, so nothing will answer you until you connect one. → Connect a model

The first connection you add that can chat becomes your Chat model, and the same dialog asks which model background work like memory summaries runs on. "Use the same one" is fine, or pick a second, cheaper model. Memory itself stays off until you switch it on.

Then say hello: Your first chat. If you're bringing a library over from SillyTavern, go to Coming from SillyTavern after you connect a model.

If the install goes wrong

• Docker tries to pull an image instead of building locally. Run docker compose -f docker-compose.yaml -f docker/compose.build.yaml up -d --build. The image is built from your copy of the code and is never downloaded.
• Another device can't open the app. That's expected on a "just me" install. See Share with friends.
• The start stops with a message naming a setting. Read the message. Every setting is checked at start, and the message names the one that is wrong and what it needs.
• Anything else: Troubleshooting.