PocketRisu: A Self-Hosted RisuAI Fork for Multi-Device Roleplay

What PocketRisu solves, and who it is for

Most AI roleplay front ends assume the browser tab is the session. Close the laptop, lock the phone, and the generation dies with the connection. PocketRisu moves that work to a server you control. The README describes it as "a self-hosted AI roleplay chat platform you run on your PC or personal server and access from PC, tablet, and smartphone through a web browser." The server keeps generating after the screen locks or the connection drops, and the finished response is restored when you reconnect. That single behavior is the reason to run it rather than a local app.

The second problem is data ownership. Characters, chats, settings and inlay images live in one SQLite database on your machine, with no external cloud dependency, according to the feature list. Backup and restore are handled server-side, and local .bin export and import still work.

This is aimed at people who already have a RisuAI habit. The project is derived from RisuAI and says existing RisuAI data can be migrated wholesale, with the wider ecosystem usable as-is: RisuRealm character downloads, .charx, .risum and .risup cards, modules, lorebooks, presets, and .bin backups with two-way compatibility. If you have never used RisuAI, PocketRisu is still usable, but you lose the main practical advantage, which is not having to rebuild a library.

How the server, SQLite database and browser client fit together

The repository layout makes the split clear. There is a src/ directory for the Svelte front end, a server/ directory for the Node side, and a Dockerfile plus docker-compose.yml for deployment. The package.json scripts show two build paths: the default vite build, and a hono:build script that runs vite build and then server/hono/src/utils/postbuild.js. The server is started with node server/node/server.cjs via the runserver script.

Storage is better-sqlite3, a native module, which is why the Dockerfile installs python3, make and g++ in the deps stage with the comment that better-sqlite3 requires native build tools on Node 24. The compose file mounts a named volume at /app/save, so the database and save data survive container replacement.

The compose file is worth reading before you assume anything about naming. The project name and container name are both risuai-nodeonly, and the volume is explicitly named risuai-nodeonly_risuai-save. The comments explain this is deliberate: the identities are kept stable so existing v1.5.x users do not hit port or container collisions, and so the volume is not re-prefixed as pocketrisu_risuai-save, which would create an empty save folder. The image itself is ghcr.io/pocketrisu/pocketrisu:latest. If you are new, that naming mismatch is confusing. If you are upgrading, it is the reason your chats are still there.

Generation is server-side, which means provider credentials and requests travel from the server, not the browser. The feature list names OpenAI, Claude, Gemini, DeepInfra, OpenRouter, Ollama and more. Anything reachable only from your desktop, such as a local Ollama instance bound to localhost on a different machine, will not be reachable from a container unless you make it so.

Installing PocketRisu with Docker Compose and opening the web UI

The repository ships a docker-compose.yml, which is the shortest path to a running instance. The compose file maps port 6001 on the host to 6001 in the container and mounts the named volume at /app/save. Create a directory, save the compose file there, and start it:

docker compose up -d

What you should see is the image ghcr.io/pocketrisu/pocketrisu:latest pulled, a container named risuai-nodeonly running, and a volume named risuai-nodeonly_risuai-save created. Then open http://localhost:6001 in a browser. The README states the UI is reachable from PC, tablet and smartphone through a browser, and that the interface is multilingual, including Korean, English, Japanese and Chinese.

If you prefer to run from source rather than the image, package.json pins the toolchain. The engines field requires Node >=22.12.0 and packageManager is pnpm@10.34.1. The Dockerfile uses Node 24 and installs pnpm 10.34.1 through corepack, so Node 24 is the version the image is built on.

corepack enable
corepack install --global pnpm@10.34.1
pnpm install --frozen-lockfile
pnpm build
pnpm runserver

After pnpm runserver, the Node server process starts from server/node/server.cjs and serves the built front end. The repository also contains install.sh, server.sh and server.bat at the top level, and the README points to a separate installation guide at docs/en/install.md, including a Termux guide for Android. Read docs/en/install.md before improvising, because the README itself does not document flags or environment variables for the server.

For a first real use, the migration path matters more than a blank install. If you have an existing RisuAI setup, the README points to docs/en/migration.md and states that .bin backups have two-way compatibility. Import your backup through the UI, confirm your characters and lorebooks appear, then start a chat and lock your phone mid-generation. If the completed reply is waiting when you reconnect, the server-side generation behavior is working as described.

Where PocketRisu is the wrong tool

The honest limitation is operational. PocketRisu is a server you maintain. That means a Node runtime at 22.12 or newer, a native better-sqlite3 build that needs a compiler on Node 24, and a SQLite file that is the single place your data lives. The README does not document rollback for a failed self-update, and it does not describe a migration path back to upstream RisuAI beyond the .bin compatibility it claims. Treat both as unverified until you test them.

If you want a hosted product with an account, no terminal, and someone else handling uptime, this is the wrong shape entirely. If you want a native mobile app rather than a browser tab, the README describes browser access only. If you run on a VPS and expose it to the internet, the security model is yours to design; the README offers a Remote access guide at docs/en/remote.md covering Quick Tunnel and Tailscale, but does not present itself as a hardened public service.

There is also a naming trap. Because compose keeps the project and container names as risuai-nodeonly, anyone writing deployment automation from scratch may assume the wrong identifiers, and anyone who renames the compose project risks the empty-volume problem the file comments warn about. That is a deliberate trade-off in favor of existing users, and it costs clarity for new ones.

PocketRisu compared with SillyTavern and stock RisuAI

SillyTavern is the obvious comparison, and the repository itself uses sillytavern-alternative as a topic. The difference is where the session lives. SillyTavern is a front end you run and open in a browser, with your data in files on the machine running it. PocketRisu puts characters, chats, settings and inlay images into a single SQLite database on the server and keeps generating server-side when the client disconnects. That is a real architectural difference, not a feature-list difference: it is what makes the phone-lock case work, and it is also what makes the SQLite file the thing you must back up.

Against stock RisuAI, the difference is deployment posture. PocketRisu is derived from RisuAI but "refined for self-hosted environments," with a Dockerfile, docker-compose.yml, install.sh, server.sh, server.bat, a self-update mechanism for portable distributions, and a dashboard for disk usage, reclaimable snapshot space and SQLite optimization. RisuAI compatibility is the point: cards, modules, lorebooks, presets and .bin backups carry over. If you are already on RisuAI and happy with how you run it, switching buys you the server-side generation model and the container packaging, not a different feature set.

Licence, updates and what maintenance actually costs you

PocketRisu is GPL-3.0. If you run it for yourself, that is unremarkable. If you modify it and distribute it, or offer a modified version to others, the copyleft terms travel with your changes. This is not legal advice; read LICENSE and, for anything commercial, talk to someone qualified.

The project is not archived, and the last push was on 2026-09-12, three days before this writing. Releases are frequent: v1.12.0 on 2026-09-06, v1.11.2 on 2026-09-01, v1.11.1 on 2026-08-31. The version in package.json is 1.12.0, matching the latest release. Frequent releases cut both ways. You get fixes quickly, and you also inherit a moving target, which is why the compose file's insistence on stable volume names matters: pinning a tag or digest is the only way to make your deployment reproducible.

Upgrade cost depends on how you installed it. The README states that portable distributions update from the web UI through automatic version detection, and the repository contains update.sh and scripts/updater.cjs. With Docker, you pull a new image and recreate the container against the same risuai-nodeonly_risuai-save volume. The README does not document a rollback procedure for either path, so back up the volume before upgrading.

Editorial conclusion

Adopt PocketRisu if you already use RisuAI and want your cards, lorebooks, modules and .bin backups to keep working while the server holds the data and keeps generating when your phone locks. Skip it if you want a hosted service, a native mobile app, or a stack you do not maintain, because you are the one running Node 22.12 and the SQLite file. Before committing, verify three things on your own hardware: that your existing .bin backup restores through the migration path, that your chosen provider endpoint works from the server rather than the browser, and that your remote-access method of choice is one you can actually operate.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. PocketRisu/PocketRisu on GitHub
3. Project website
4. README
5. Releases