Privacy and Security

If you run Orbweaver in Docker because you don't fully trust it yet, good instinct. Docker is a fine way to run it. Below is what the app does on its own: where your things are kept, what leaves your computer and when, and what protects you once other people are involved.

The short version

• Orbweaver runs on your computer and keeps everything in one data folder.
• Almost nothing goes out on its own. Two things happen without you asking: a one-time download of the built-in search models, and a daily fetch of OpenRouter's public model list. Neither sends your content. Everything else is listed below, and each one happens because you connected a model, switched something on or pressed a button.
• A fresh install has no login and answers only on the computer it runs on, so only programs on that computer can reach it.
• Saved API keys are encrypted and never shown again. Your chats and characters are not encrypted on disk.
• There is no telemetry, analytics or crash reporting.
• Plugins and interactive story cards run in sandboxes. The limits of those sandboxes are stated below.

The code is open source, so none of this has to be taken on faith. Go read it.

Where your data lives

Everything Orbweaver keeps is in one data folder. With Docker it's a volume called orbweaver-data. From source it's the data folder inside the Orbweaver folder. → Install

Folder	What's in it
db	The database: characters, chats, personas, world books, settings, memory, accounts, and your saved keys in encrypted form
assets	Images and other files you uploaded or generated
users	Each account's own working files
secrets	The two key files, covered below, plus any HTTPS certificate files and, in Docker with password sign-in, the password it generated for you
backups	Copies of the database that Orbweaver makes before an update changes it
reports	Reports from imports
cache	Things Orbweaver can download or build again: the search models, resized images, the share tool. Leave it out of a backup.

How it's protected:

• Saved keys are encrypted. A provider key is encrypted before it's written to the database, tied to your account and that provider, and the browser is never sent it back. After you save a key you can replace or revoke it, but not read it. The decryption key sits in the secrets folder, apart from the database. That keeps a stray copy of the database from leaking your keys. It doesn't protect against someone who can read your whole data folder.
• Everything else is plain data. Chats, characters and memory sit in the database file as ordinary data. If you want them unreadable to someone who steals the disk, turn on your operating system's disk encryption.

If you turn on sign-in, passwords are stored as salted hashes, never as the password itself, and sign-in attempts are throttled. The second key file in secrets is mixed into those hashes. Both key files are created readable only by your account.

What leaves your computer and when

Orbweaver doesn't run the language model, so the prompt is by far the biggest thing that leaves. The whole list:

What	When	Where it goes
The prompt for a reply: your messages, the character card, your persona, world book entries and any recalled memories	Every reply	The provider or server you picked for Chat. A model on your own machine keeps it there. Connecting a server also asks it for its model list.
Background work: memory summaries, image captions, the optional Utility speaker picker, the Refinery and library analysis	Only while those features run	The provider or server you picked for your Utility model
Smart speaker selection	When Smart needs to choose the next speaker	The host's Rerank model, which runs locally by default, or the host's Utility model if they choose that option
Generated images	When you ask for one	The image provider you set up
The built-in search models	Once, shortly after the first start, or the first time a feature needs them if you turned the automatic download off. Skipped for any search role you point at your own server or a hosted provider.	Hugging Face's model hub. Afterwards, search by meaning and memory recall run on your computer.
OpenRouter's public model list	Shortly after a start when the last copy is over a day old, then about once a day while Orbweaver runs. It happens even if you never use OpenRouter.	OpenRouter. The request carries no key and none of your content.
A plugin's requests	Only for a plugin you've enabled and allowed to reach the internet	Only the sites on that plugin's approval screen. Card Atlas browses card hubs, and Research Familiar looks things up on Wikipedia.
Installing a plugin from a link, or pressing Check for updates in Plugins	When you do it	The address you gave. The update check asks the source of each plugin you installed from a link.
A web page, wiki article or YouTube captions you add to Databank with From a link	When you add it	The address you gave
The share link	When you start sharing. The first time, Orbweaver downloads Cloudflare's tunnel program from GitHub and checks it before running it.	GitHub for that one download, then Cloudflare for as long as you share
An HTTPS certificate	Only if you set up HTTPS at your public address	Let's Encrypt
Single sign-on	Only if you set it up	Your identity provider
The update check	Only when the owner or an admin presses Check for updates under This install in Settings	One request to GitHub for the newest release or commit. It identifies the app and its version, and nothing else about you or your setup.
A picture you paste by web address, such as a background	When you paste it	Your server downloads it from that address

Notes on that table:

• Whoever answers sees your address. Every request above shows your internet address to the site that receives it, like any website you visit.
• Search and memory stay local unless you change that. The built-in models turn text into searchable form on your own computer. If you point the text embedding role at a hosted provider instead, the text being indexed goes to that provider. A plugin allowed to search your library can send its queries the same way.
• A hosted model sees what you send it. Orbweaver can't change that. The provider's terms apply to everything in the prompt. If that matters for a story, use a model on your own machine. → Connect a model

What doesn't leave

• No telemetry. Orbweaver has no analytics, tracking or crash-reporting service built in. Errors your browser hits are written to your own server's log.
• The page only talks to your server. The app's security policy blocks the page in your browser from connecting anywhere else, and the scripts and fonts come from Orbweaver itself.
• Pictures from web addresses in messages don't load. Loading one tells whoever hosts it that you read the message, so Block external media is on by default. It lives under Media & trust in the admin settings, and its in-app help has the details. A character can also block outside media for itself, and then its messages never load pictures from other sites, even with rich HTML on. Pictures hosted on your own Orbweaver still show.
• Fetches stay off your network. When Orbweaver fetches an address on your behalf, such as a plugin install link or a pasted image, it refuses addresses on your own network. That's also why the owner has to admit a model server that lives on your network. → Connect a model

Ways to sign in

Orbweaver has four sign-in modes, and the mode decides who can get past the front door. The setup questions offer "just me", and "me and friends" with password sign-in. The other two take extra settings.

• Just me. No login at all, and only the computer it runs on can reach it. This is the default. Whoever is at that computer is the owner.
• Password sign-in. Accounts with a password stored by Orbweaver. The owner sets the owner password the first time (Docker makes one on first start), and friends join by invite link or an account the owner creates. This is the mode sharing needs.
• A login proxy you already run. If Authelia, Authentik or something similar already sits in front of your apps, Orbweaver can trust who it says you are. Orbweaver believes the proxy's headers only when they come from a proxy address you listed, or when they carry a signed token it can check. Keep the proxy as the only way to reach Orbweaver, because anything that reaches it from a listed proxy address can set those headers.
• Single sign-on (OIDC). People sign in through your identity provider and Orbweaver never sees their password. New accounts are not created automatically: a person with no account yet is turned away until you switch on sign-ups for it. You can also require approval, so a new person waits in the Approvals list under the admin settings until an admin approves them. The owner is never held up. Both are off until you turn them on. On first start, the one-time link that makes you the owner is written to a file, never to the log, so a pasted log can't hand your box to someone else. Read it with docker compose exec orbweaver cat /app/data/secrets/owner_claim_url. The file is deleted once you sign in.

If you move an existing install to single sign-on, use Link SSO identity in the admin settings to attach each person's identity to their existing account. That way their first single sign-on lands on their existing account, with their chats and characters, rather than a new one. The owner doesn't need this.

Single sign-on and the login proxy need settings that the setup questions don't collect. → Install

The sign-in page also has a resident spider weaving a web behind the card. The silk rings where your cursor or thumb crosses it, and the spider comes over to look. It's decoration only, and it stays still if your system asks for reduced motion.

What "just me" protects

A fresh install has no login, so what protects it is where it listens. You are the owner without signing in. A server with no login that other devices could reach would make every one of them the owner, so "just me" is the default, and sharing is something you switch on.

• It answers only on your own computer. If you try to open a no-login install to a network, it refuses to start rather than quietly making everyone on that network the owner.
• A web page can't use your browser as a bridge. Orbweaver answers only to localhost, IP addresses and names you've told it about, which stops a hostile page from reaching your local copy through your browser.
• The Docker setup is already locked down. By default the port is published on your computer only. The container's filesystem is read-only apart from your data volume and scratch space, it can't gain extra privileges, it drops the Linux capabilities it doesn't need, and the app doesn't run as root.

Docker adds a wall between Orbweaver and the rest of your computer, and from source, Orbweaver runs with your account's permissions. But Docker changes nothing about what leaves, because the table above is the same either way.

What changes when you share

Sharing turns a closed install into one reachable from outside, so it needs more.

• Sign-in comes first. Sharing needs a password sign-in and an owner password. Starting a share also turns on Allow multiple humans and Discreet login, and they stay on afterward. The steps are in Share with friends.
• The link only gets people to the sign-in page. Anyone with the link reaches that page, but only an account gets past it. The link is a random name that changes every time you share.
• Friends' traffic passes through Cloudflare. The link runs through Cloudflare's free quick tunnel on its way to your computer.
• Plain http gets a warning. On your home network a sign-in travels unencrypted. The sign-in page and the share card both say so. A share link uses https.
• Never forward a router port straight to Orbweaver over plain http. Your password would cross the internet in the clear. The link, or HTTPS at your public address on the share card, are the ways in.
• Don't put a proxy or tunnel of your own in front of "just me". A relayed visitor is never the owner, so everything answers with an error. Turn on sign-in first.
• Single sign-on and login proxies can't use the link. Sharing is refused when Orbweaver is set up that way.
• Your models answer for everyone, so your provider sees what friends type. In a room you host, every reply runs on your Chat model. What friends write goes to your provider along with the rest of the prompt. Friends need no key of their own and can't see yours, because a saved key belongs to the account that saved it.
• The host sees more than the other people in the room. Preview, View wire trace... (the exact prompt behind a reply) and the memory recall detail are host-only. If a game has Deception switched on, characters can hide things from the other players, and the host can still see them unless the host turns off Let me reveal hidden content.
• Stopping is immediate. Stop sharing kills the link at once. Friends who are already signed in stay signed in until their sessions expire, unless you press Sign everyone out.

Plugins

A plugin is someone else's code, so Orbweaver treats it as a guest.

• It runs in a sandbox. Plugin code runs inside WebAssembly in a separate helper process. That process has no network access of its own and can't read your data folder. A plugin has to ask Orbweaver to do anything, and Orbweaver checks every request against what you approved.
• It does only what you approve. A plugin starts switched off. Its approval screen lists in plain words what it wants, including the exact websites it may contact, and it can do only what you allow. The nine example plugins arrive installed, switched off, with nothing allowed yet.
• More access means asking again. If an update asks for more than you approved, the plugin stays off until you approve the new request.
• The limits. A plugin can do everything you approve, so read the screen. The two channels no sandbox closes are listed under Two limits. The helper process also has memory and time limits, and it's restarted if it overruns them.
• On a shared install, every account can install plugins. Anyone you give an account installs plugins for their own account, approves them for themselves, and those plugins run in the same sandboxed helper process on your machine. If you don't want that, don't open the install up.

→ Plugins

Interactive story cards

The story can hand you small in-world pages, like a letter, a wanted poster or a ship's terminal you can click through. Interactive cards are on by default for every character. A card shows in a locked-down frame with its own styling, and it runs its own code there.

That code is sandboxed: no cookies, no storage, no access to the app or to other cards, and no way to send you somewhere else. It can't make network requests of its own, and while Block external media is on it can't load outside pictures or video either.

Two settings turn cards down:

• For one character: open its Trust tab and set HTML rendering to Render HTML (rich HTML and card styling, no scripts) or Untrusted (plain, sanitized text). A character on Inherit default, which is every character until you change it, gets Interactive.
• For yourself: turn off Run story-card scripts under Chat behavior → Message handling in your settings. Every card then shows without its scripts in your browser, including cards in rooms other people host. A card already open stops at its next load.
• For everyone: an admin switches off Let interactive cards run their own scripts under Media & trust. That's the off-switch. Orbweaver checks it every time a card loads, so a card already on screen loses its scripts the next time it loads.

One thing the sandbox can't stop is the second limit below: a card's code can use WebRTC to tell its author that you looked at it, reveal your internet address, and capture what you type inside the card itself. No browser policy blocks that, and it's the trade for cards that do something. Don't type anything private into a card, and if you'd rather not take the trade at all, switch it off.

Two limits the sandboxes can't close

1. An isolated-frame plugin. A plugin that draws its own screens in an isolated frame can send what it's allowed to read out through browser channels that no policy closes. Its approval screen says so. Approve that only for a plugin you trust.
2. An interactive story card. A browser feature called WebRTC can't be blocked by any policy, so a card that runs its own code can tell its author you looked at it, reveal your internet address, and read what you type inside the card. The admin switch Let interactive cards run their own scripts closes it for everyone, and Run story-card scripts in your own settings closes it for you.

Backups and the secrets folder

A backup is a copy of your data, so it holds everything the data folder does.

• Keep the secrets folder with the database. One key file decrypts your saved provider keys, and the other is what passwords and sign-ins are checked against. A database without them can't read its keys or sign anyone in. If a start finds one of them missing while the database still needs it, Orbweaver stops and names the file instead of quietly creating a new one that would orphan your keys.
• Guard a full backup like a password. A copy that includes secrets has the keys and the data they unlock together. In Docker with password sign-in, it also holds the password Orbweaver generated for you until you delete that file. Store it somewhere only you can read.
• The backups folder holds whole copies of your database. Orbweaver makes one before an update changes it, so each copy has all your chats in it.
• Backup & Restore exports your library, not your keys. The zip carries characters, chats, personas, world books, presets and the like. It has no saved keys in it, but it does have your chats, so treat it as private too. → Back up and restore

What Orbweaver can't promise

• Your provider's handling of your prompts is theirs. See the note under the table above.
• Story features aren't security boundaries. Characters keeping secrets, or remembering only their own scenes, shape the story. The model still gets what it needs to write the reply, and the host can look behind them.
• Installing downloads other people's code. Both the Docker build and pnpm install fetch the app's dependencies from the package registry. The project pins their exact versions in a lockfile, runs install scripts only for the few packages on an allowlist (allowBuilds in pnpm-workspace.yaml), and, with named exceptions, waits a day (minimumReleaseAge) before adopting a brand-new release. They are still other people's packages.
• A file on your disk is only as private as your disk. See the encryption note under Where your data lives.

Found a security problem? Report it privately through GitHub Security Advisories rather than a public issue.