STEP 1
Import a character card
Works with SillyTavern V1, V2 and V3 character cards, as PNG or JSON files. The card's image becomes the story cover, and its lorebook is used to build the opening world.
BetterTavern
Interactive fiction played with SillyTavern character cards. The AI writes a passage in the first person and ends it with two choices; to do something else, write your own line.
For now you run the server yourself. On Android you can install the APK directly; the iPhone app isn't on the App Store yet, so you open it with Expo Go; the web version runs locally.
Fog Harbor Watch
The fog came in off the sea. By the time I reached the end of the pier, it had swallowed the railings. The lighthouse stood just ahead, but its lamp was dark. Old Hale had written in his letter: once the Fog Harbor light goes out, someone has to go and light it again — and the man who wrote that letter had been missing for three days. Behind me a bell rang once, low and wet, as if it had floated up from under the water.
Pick a choice to read on. You can also rename the protagonist, switch to dark mode or open the world state. In real use, every passage is written by the model you set up.
Character cardsSillyTavern V1, V2 and V3, as PNG or JSON
ModelsDeepSeek, OpenAI, Grok, Gemini, Hugging Face, or any OpenAI-compatible API
ServerPython (FastAPI) and PostgreSQL, deployable with Docker Compose
Interface中文 · English · 日本語
01
Start a story
You need a character card and a name for the protagonist. Everything else can stay blank.
STEP 2
Name the protagonist
The name is required. You can also pick a role (a passing traveler, an old acquaintance…) and set how long each passage is and what style it's written in. One card can start several stories.
STEP 3
Read a passage, pick a choice
The AI writes the next passage in the first person and ends it with two choices. Pick one to go on; to do something else, tap “Write your own”.
02
World state
At the start, the AI reads the character card and sorts out the people, places, items, groups and secrets. Every passage after that is written against this record, and the record is updated as the story moves on.
- People, places, items and groups, each with its current state
- A relation map: who is where, who holds what, who is tied to whom
- Secrets the protagonist doesn't know yet stay hidden until you confirm
1 hidden secret
Hover over a node to highlight its relations; click for details.Tap a node to see its details and relations.
ProtagonistMe · Rowan
The new night watch. Goal: light the lamp again.
in theLighthouse
03
Long stories
The director model writes the story. The world state, recaps and outline are kept up to date in the background without holding up the next passage. Each passage is written with all of them in context, and for older details the director looks up the original text.
AGENT RUNTIME
One turn: who does what
Player waits · api process
Read: recap, text, state, outlineRecall past turns (read-only, ≤ 2 rounds)Save the turn, queue a job
PostgreSQLData and the job queue live here
TurnsTurn notesWorld stateThreadsChapter summariesSynopsisPlayer profileOutlineUndo recordsJob queue
Take job · write world stateTake job · write summary & profileTake job · write outline
Background · worker process · background model
Recaps
When a chapter ends, the background turns it into a chapter summary, and older chapters are folded into a synopsis of the whole story. The original text is always kept; the state of people and places is stored separately, so nothing is lost along the way.
Long-range outline
The outline splits the main plot into beats, and the director sees the current beat while writing every passage; when the story drifts, the background revises the outline. Foreshadowing that hasn't paid off yet is tracked separately as threads.
Go back
Return to any earlier part and choose again. The world state, recaps and outline all go back to how they were at that point. Each save can go back a limited number of times, once by default.
Write your own
For an action that isn't among the choices, tap “Write your own” and tell the director in one line what you do.
Resume after a disconnect
If the network drops or the app goes to the background, writing picks up where it stopped when you come back — nothing repeated, nothing missing.
Write the ending
Under “More”, tap “Write the ending”. You can describe the ending you'd like, and the AI writes one long final part.
04
Models & data
Models
Add them under Settings → Models: pick a provider, paste an API key, and the model list loads by itself. You can add several and switch the one writing your story with a tap. The provider bills you for what you use.
API KeyGet a key from DeepSeek
sk-…Paste
Keys are stored encrypted; after that only the last four characters are shown: •••• 3f9a
Where your data lives
ClientsPhone, tablet, web
Your serverStories, world state, encrypted keys
Model providerOnly gets the context needed for this passage
- Stories, world settings and model keys are all stored on the server you run. Keys are encrypted, and the app only shows their last four characters.
- The server sends the needed context to the model provider you chose only while it's writing the story.
- The server's logs record neither story text nor keys.
05
Clients
The phone, tablet and web clients connect to the same server and share accounts and stories. The look can follow the system or stay light or dark; the story text can be serif or sans-serif, at an adjustable size.
Phone
iOS and Android
React Native (Expo), one codebase for both platforms. On Android, download and install the APK; the iPhone app isn't on the App Store yet, so for now you open it with Expo Go.
Tablet
iPad and Android tablets
The same app as on phones. On wide screens the text is centered and the world panel can dock beside it.
Web
Desktop browsers
Has a sidebar and keyboard shortcuts; drop a character card file onto the window to import it. Start it locally with make web.
06
Deploy
There's no public service yet. Run the server on your own computer or a cloud host and connect the clients to it.
What you need
- Server: Docker; or Python 3.12+ with uv, and PostgreSQL 16
- Clients: the APK on Android; on iPhone, Expo Go plus Node 22.18+ on your computer
- Model: An API key from a provider, or a local model with an OpenAI-compatible API
Before the first production start, generate the master key and the token signing key. If the master key is lost, saved model keys can't be decrypted, so back it up separately.
$ git clone https://github.com/Hexthebaldy/BetterTavern.git$ cd BetterTavern# Generate the keys and put the two output lines into deploy/.env$ docker compose -f deploy/docker-compose.yml run --rm migrate bettertavern keygen$ docker compose -f deploy/docker-compose.yml up -d# The API listens on 127.0.0.1:8000; for outside access, put it behind a reverse proxy with TLS
$ git clone https://github.com/Hexthebaldy/BetterTavern.git$ cd BetterTavern$ cp apps/server/.env.example apps/server/.env# Starts PostgreSQL in Docker; with a local PostgreSQL 16, skip this line and set DATABASE_URL in .env$ make db-up$ make install && make migrate$ make dev# In another terminal, start the background worker that updates the world state$ make worker# API docs: http://localhost:8000/docs
$ make js-install$ make web# Open http://localhost:5173 in a browser# To deploy, run make web-build to produce apps/web/dist and serve it on the same domain as the API
$ cp apps/mobile/.env.example apps/mobile/.env# Change the address in apps/mobile/.env to your computer's LAN IP$ make mobile-install$ cd apps/mobile && npm start# Scan the QR code in the terminal with Expo Go on your phone
No. BetterTavern is open source. Stories are written with your own model key, and the model provider bills you for what you use.
Yes, there's no public service for now. Stories, the world state and keys are stored on the server you run; an always-on computer or a small cloud host is enough.
Android: tap “Download for Android” at the top of this page to get the APK. When installing, your phone asks you to let the browser or file manager install apps; allow it. It isn't on Google Play yet. iPhone: not on the App Store yet; for now open it with Expo Go: start the client on your computer (see “Mobile” under Deploy above) and scan the QR code in the terminal with your phone. The phone and computer need to be on the same network, or connected with a tool like Tailscale. After installing, enter your server address at the bottom of the sign-in page.
SillyTavern character cards: PNG images or JSON files, V1, V2 or V3, up to 16 MB. A PNG card keeps its data inside the image file, and compressed images or screenshots lose that data, so use the original file.
Yes. When adding a model, choose “Custom compatible endpoint” and enter the URL of an OpenAI-compatible API. If the endpoint is on the same machine or local network, set ALLOW_PRIVATE_ENDPOINTS=true on the server.
At the start the AI builds the world state; after every passage the background updates it to match the story, and the next passage is written against it. When a chapter ends, it's condensed into a summary; the background also keeps an outline that the director follows; for older details, the director looks up the original text. If things go off track, you can go back to an earlier part and choose again.
The interface is in Chinese, English and Japanese; switch under Settings → Language. The story itself isn't tied to one language; it usually follows the interface language at the start, the character card and what you write.
BetterTavern doesn't collect story content. While writing, the needed context is sent to the model provider you chose, and how they handle it is up to their terms. If that concerns you, use a model running on your own computer.