FAQ - Inktomi93/OrbWeaver GitHub Wiki

Quick answers, each pointing at the page with the full story. If yours isn't here, ask.

Getting started

What do I need to run it, and does it work on my system?

Linux, macOS and Windows all work. You install it with Docker or with pnpm, and you open it in your browser. There's no one-click installer. You don't need a graphics card, because Orbweaver doesn't run the language model itself. You point it at a model you pay for or a server you already run. → Install

Can I use it on my phone?

Yes, in the phone's browser. The layout adapts, and you can add Orbweaver to your home screen from the browser menu. Browsers generally want HTTPS before they let you install a site like an app, which a share link gives you and a plain address on your home network usually doesn't. There's no native app, and Orbweaver itself keeps running on your computer or home server. By default only that computer can open it, so your phone needs either a share link or the "me and friends" sign-in. → [Install]], [Share with friends

Is it free?

Orbweaver is free and open source under the AGPL-3.0 license. The model you connect may not be: hosted providers charge you for what you send, and a model on your own machine costs only your electricity. → Connect a model

Where do I get characters?

Make your own, import a character card (PNG or JSON), or bring over your whole SillyTavern library in one import. The Card Atlas example plugin can also browse the big card hubs, once you turn it on and approve what it may access. → Coming from SillyTavern, Characters and personas, Plugins

Models and cost

Which models can I use?

Hosted: Google Gemini, OpenRouter, Anthropic and OpenAI, each with an API key. On your own machine or network: Ollama, LM Studio and vLLM, which have their own entries, or anything else that serves an OpenAI-style chat endpoint, such as KoboldCpp, TabbyAPI or llama.cpp's server, through Custom OpenAI-compatible. A server needs only a URL, and a key only if it asks for one. You can keep several connections and choose which one does which job. → Connect a model

You can also chat on a Claude subscription, at your own risk: it may bill as extra usage, and Anthropic limits third-party use of subscription logins. The Connect page explains before you try it.

Does it work with local models?

Yes. Point a connection at your model server's URL, press List models, and pick yours. You can include /v1 on the URL or leave it off. In Docker, a server on the same computer is reached at host.docker.internal instead of localhost, and the owner admits that address once with the Admit button the dialog offers. Game mode updates its own state only with a model that makes tool calls, and for a model Orbweaver doesn't recognize you can declare them under the connection's Advanced. A small model on your own server can also be your Utility model for background work. → Connect a model

Does it support text completion?

No. There's no text-completion mode; replies go through a chat API. Text Completion, KoboldAI and NovelAI presets and the Context and Instruct templates don't come over, and the import report lists them. If your backend also serves a chat endpoint, which most local servers do, connect to that. → Coming from SillyTavern

Do I need two models?

No. Only Chat is required to start chatting. The Utility model is a second, cheaper model for background work, and you can point it at the same connection as Chat if you'd rather run one model. Either way, its connection needs Allow background work switched on. Without a Utility model, memory summaries stay paused and image captions are skipped. Smart normally uses your Rerank model, built in and local by default; only its optional Utility picker needs Utility. Your first connection asks which model it should be, with Use the same one as a choice. → Connect a model

Will the background features burn through my tokens?

Some can, so here is which model each one runs on. What that costs depends on your model and settings.

• Memory summaries run on your Utility model, while Memory is on. Memory is off until you turn it on, and turning it on tells you the cost first. Recall uses your Text embedding and Rerank roles, which run locally by default.
• The Smart speaker picker normally uses the host's Rerank model, which runs locally by default. Choose Use the Utility model instead to use Utility calls. Natural makes no model call, and a Narrator room does not need a speaker picker.
• Image captions and /imagine prompts run on your Utility model.
• The Refinery and Corpus analysis run on your Utility model, only when you start them. A run over your whole library shows about how many model calls it will make and asks before it starts.
• Game mode updates the game inside the reply. On some setups it needs a second pass after each reply, on your Chat model, and the game panel says when it does.

Give the Utility model a small model, and leave Memory off if you don't want the summaries. The host can open Preview before sending to see what the next turn contains and what each part costs in tokens. → Connect a model, Rooms and group chats, How a turn is built

Can I use a different model for one chat?

No. There's no per-chat model. Replies run on the Chat model of whoever hosts the room, which in your own chats is you. To change models, change your Chat role. → Connect a model

Memory and games

What memory system does it use?

As a chat grows, a small model writes a short summary of each block of messages (8 by default). Older summaries roll up into broader ones, in up to three levels, so a long chat stays compact. When an old moment becomes relevant again, Orbweaver finds it by meaning and by keyword, reranks the matches, and brings the best ones back into the scene. Memory is off until you switch on Remember earlier in long chats, which tells you what it costs before it turns on, and it needs a Utility model for the summaries. → How memory works

Can characters in a group only know what they were there for?

Partly, and only if the host sets it up. Turn Memory on, switch the group to Per-speaker replies, and turn on Each character sees only their own card in the group's advanced settings. A character then recalls only memories from while they were seated in the room, so someone added later won't recall what came before, and someone removed for a while misses that stretch. It goes by who was seated in the room, whatever the story says, and it filters recalled memories only. The recent messages stay shared. → How memory works, Rooms and group chats

What do I need for game mode?

Just turn it on for a chat you host. A game starts in Freeform, with no dice and no attributes. The D20 ruleset is a setting you can switch on any time to add six attributes, a health meter and dice. For the story to update the game by itself, use a model that supports tool use; without one, the host fills the game in by hand. Switch game mode off and nothing is lost. → RPG mode

Friends and sharing

Can my friends play in the same scene?

Yes. They open a link in their browser and join your room live. By default Orbweaver is "just me" with no login, so inviting friends takes a few steps: switch on password sign-in, set an owner password, turn on Allow multiple humans and Discreet login, then press Start sharing as the owner. The first time, it downloads a pinned copy of Cloudflare's relay tool, and the link changes each time you share. From source, answering me and friends at pnpm start --setup does the sign-in part, and pnpm share is a one-launch shortcut. → Share with friends, Rooms and group chats

Who pays when friends play?

The host. Every turn in a room, including your friends', runs on the host's Chat model. Memory summaries run on the host's Utility model. Smart normally uses the host's Rerank model, or Utility when the host chooses that option. Friends need no key of their own. If you hand the room to someone else, their connection pays from then on. → Connect a model

Is sharing safe?

Friends have to sign in with an account, one you create for them or one they make through a sign-up link you hand out, so the share link alone isn't enough. Sharing runs only while you have it on, and Stop sharing ends the link at once. Friends who are already signed in stay signed in until their sessions expire, unless you sign everyone out. Your saved API keys are never shown to anyone after you save them. → Share with friends, Privacy and security

Safety and your data

Is it safe to run?

Your characters, chats and saved keys live on your machine. Messages go only to the models you connect. It has no telemetry. It downloads the built-in search models automatically and refreshes OpenRouter's public model list about once a day, even without an OpenRouter connection. That catalog request carries no key or content. The sharing relay downloads the first time you share; update checks run only when you press the button. Plugins can reach only the sites you approve. If you'd like another layer, run it in Docker.

Plugins run in a sandbox, show you what they want to access before they run, and can only do what you approve. The example plugins arrive switched off. HTML cards the story sends, like a letter or a notice, show in a locked-down frame. Cards you can click through are on by default, and their scripts run inside that frame. A card's script can still tell its author you looked at it, so don't type anything private into one. An admin can switch them off for everyone with Let interactive cards run their own scripts, and you can turn one character down in its Trust tab. → Privacy and security, Plugins

Where does my data live?

In one data folder. With Docker it's a volume called orbweaver-data, and from source it's the data folder inside the Orbweaver folder. It holds your characters, chats, settings, images and your saved keys. → Install

How do I back up?

Two ways. Backup & Restore in Settings exports your library as a zip you choose the parts of. With Orbweaver stopped, copying the whole data folder (leave out its cache) backs up everything, including accounts and settings. Keep the secrets files with any copy, or the saved keys and sign-ins can't be read back. → Back up and restore

How do I update?

Run ./update.sh, or double-click update.cmd on Windows. It waits for a running Orbweaver to stop cleanly, pulls the latest code and starts it again. Your data stays where it is, and Orbweaver copies your database before it changes it. Updates only go forward, so make a full backup before a big one. → Install

Compared with SillyTavern

Is it a SillyTavern replacement?

No, and it isn't trying to be. Orbweaver leans toward playing with friends in the same scene, turning a story into a game, and long chats that remember. SillyTavern is brilliant at plenty of things Orbweaver doesn't try to do. Import your library, keep both, use whichever fits the evening. Import adds and never updates or deletes what you have. → Coming from SillyTavern, Credits

What doesn't it do that SillyTavern does?

Text-completion presets (by design: there's no text-completion mode), user-authored Quick Reply buttons, the advanced lorebook activation fields (secondary keys, probability, recursion, sticky and cooldown), and Data Bank file and gallery image import. STscript doesn't run here because Orbweaver has its own macro language: 68 built-in macros including if/else, chat variables and global variables, plus macros you write yourself with arguments, typed inputs and seeded random picks. Forking is there too: fork any chat from any message. The full list, with what works differently, is under "What isn't supported" on the Coming from SillyTavern page. → Coming from SillyTavern

Will my SillyTavern extensions work?

No. Orbweaver has its own plugins, and SillyTavern extensions don't run in it. The import doesn't bring extension installs over, and the report says so. → [Plugins]], [Coming from SillyTavern

Is this vibe-coded slop?

One dude built it, with tools. The authors of the code are AI agents that forget everything when their context compacts, so the structure has to be the memory. In practice that's about 3,000 test files (unit, integration, component and end-to-end, in a real headless browser), 353 custom checks of the repo's own structure, types and imports on top of a strict shared TypeScript config, dependency-cruiser import rules, dead-code and copy-paste detection, and custom screenshot and headless-browser tooling for the UI. The UI is our own kit on Base UI's headless parts: Base UI supplies the behavior, and the components, tokens and skins are ours. I'm the guy who grows the tree to mill the wood for his own chair, and I find that calming. "Alpha" here means rough edges, plus a few SillyTavern features that aren't in yet. The rough edges are on Known issues and the missing features are under "What isn't supported" on Coming from SillyTavern. The full tour of the rigor is on Under the hood.

When something's wrong

Send is greyed out, or another device can't open Orbweaver

Send stays off until you add a connection and pick a Chat model under Model roles. Another device can't connect on a "just me" install, by design. → Connect a model, Share with friends, Troubleshooting

How do I report a bug?

Press Report a bug, the bug icon in the top bar. Say what happened, press Prepare report, read what it holds, then press Copy and open a GitHub issue. The report carries the app version and the types of recent errors, and leaves out your chats, keys and error messages. Nothing is posted until you submit the issue on GitHub. Report security problems privately through GitHub's Security Advisories instead of a public issue. → Report a bug