![]()
Fablewright #
Long stories welcome.
Fablewright is a free, open-source, self-hosted place to write a novel. Your manuscript lives on a server you control. It saves as you type and exports in open formats. No subscription tiers, no telemetry, and no generative AI. Every instance has every feature.
If someone already runs an instance for you, start with the writer's guide. It is also available at /help inside the app. To host your own, use the installation guide or the quick start below.
What it does #
Write and read #
A project holds one or more books. Books hold optional parts, chapters, and scenes. The manuscript tree shows the word count at every level. Each book can also have front and back matter pages.
The rich-text editor has Markdown-style shortcuts, autosave, find and replace, scene versions, focus mode, and scene read aloud. Search covers scenes and story notes. Optional daily goals count your own words added, without subtracting deletions, and a goal can carry a deadline with its own pace. The read-through shows a project, book, or chapter as continuous prose for reading, printing, or saving as PDF.
The editor, with the manuscript tree alongside the draft.
Read a whole project, book, or chapter in the read-through. This view uses Safe Mode, the light color mode.
Plan beside the draft #
Keep notes for characters, places, objects, and ideas, or make your own note types and templates. Each note can hold an image and link to scenes. The plot grid puts storylines against chapters or scenes. The outline shows summaries, draft status, and word counts. The scene panel also records a viewpoint.
Keep story notes beside the scene you are writing.
The plot grid maps storylines across scenes or chapters.
Share and review #
Invite an existing account as a reader or co-author. Readers can read and comment. Co-authors can also write, plan, export, and use recovery. Expiring secret links let guests read, comment, or edit scene prose without an account. A link can cover the whole project or one book, chapter, or scene.
Feedback can refer to a passage, scene, or chapter. A suggested replacement stays a suggestion until a writer applies it. A secret link follows the live part, not a frozen review copy. There is currently no real-time co-editing. The sharing guide explains the permissions and limits.
Keep your work and take it elsewhere #
Recovery restores deleted work and earlier scene, note, and plot-card versions. A project version opens as a separate copy.
Export a whole project or one book, chapter, or scene to Word, EPUB, or print. A project archive carries manuscript.json, readable Markdown, and note images. Import accepts those archives, standalone manuscript JSON, Word, Markdown, plain text, and Scrivener folders or ZIPs. Each import creates a new project. Word, text, and Scrivener imports show a preview before they write anything. The import and export guide explains what each format keeps and loses.
Run your own instance #
One app process uses one SQLite database and an uploads directory. Accounts use email and password (with optional passkeys). The first account becomes the admin, and claiming the instance closes sign-up until the admin opens it. Writers manage their passwords, passkeys, and sessions on Your account.
Fonts and the optional spelling and grammar checker come from the instance. The checker runs in your browser and sends no manuscript to another service. The server operator can still read the database, uploads, and backups. Fablewright does not currently provide end-to-end encryption.
How saving works #
The server holds the saved copy. The editor waits for a short pause before sending changes and keeps a local recovery buffer between saves. Unsaved words carry heat until the server confirms them. Reduced heat keeps the prose in ink and puts the save state in the status bar.
If a save fails, the editor keeps the words, reports the failure, and retries. If another tab or writer saves the scene first, Fablewright asks which version to keep instead of silently overwriting it.
Fablewright needs a connection to save. The browser buffer is a safety net, not offline drafting or a project backup. Browser storage can be blocked, cleared, or lost. Keep a failed-save tab open and download its words before troubleshooting.
Accessibility and browser support #
Digital Rust, the dark theme, and Safe Mode, its light projection, are always available. Text roles have WCAG 2.1 AA contrast tests in both modes. Keyboard controls cover the editor, manuscript tree, and dialogs. Reduced motion is respected, and Your account offers Lexend as an alternative body font for dyslexic writers.
These are tested features, not a claim of complete WCAG conformance. DESIGN.md records the contrast measurements and exceptions. Automated browser tests run in Chromium. The web layout adapts to phones; there is currently no separate mobile app.
Run it #
Use Docker Compose, Node 24 or newer, or Cloudron 10.0.0 or later. Claim a new instance before you expose it publicly: whoever creates the first account becomes its admin.
Docker Compose #
Install Docker Engine with the Compose plugin. Then get the repository:
git clone https://tangled.org/katsuricata.com/Fablewright
cd Fablewright
docker compose up -d
Open http://localhost:3000 and create the first account. It receives an example project, The Wonderful Wizard of Oz. Any writer can add a fresh copy from Your account.
The Compose file pulls katsuricata/fablewright:1.0.0 from Docker Hub. The fablewright-data volume holds the database, generated signing secret, and uploads. Do not use docker compose down -v unless you intend to erase that volume.
The Compose file pins an image version. To change it, set FABLEWRIGHT_TAG in .env, then pull and restart after taking a backup. Do not copy the development .env.example unchanged for Compose. Its ORIGIN points to port 5173.
Bare Node #
Install Node 24 or newer, Git, and pnpm 12.21.0 or newer. From a checkout:
mkdir -p .agents/skills
pnpm install --frozen-lockfile
cp .env.example .env
Edit .env before building. Set ORIGIN to http://localhost:3000 for a local production trial, or your public HTTPS address. Set BETTER_AUTH_SECRET to at least 32 random characters. Then run:
APP_COMMIT=$(git rev-parse --short HEAD) pnpm build
node --env-file=.env server.js
Use server.js, not node build. It handles the request scheme and refuses an older build against a newer database. Node does not read .env without --env-file.
The installation guide covers persistent storage, systemd, and the files a production install needs. Do not run real writing from a test checkout.
Cloudron #
Install the Cloudron CLI on your workstation and sign in to your server. Install the published package from the community catalogue:
cloudron install --versions-url https://tangled.org/katsuricata.com/Fablewright/raw/main/CloudronVersions.json
Cloudron supplies HTTPS, storage under /app/data, and outgoing mail. Fablewright uses its own accounts, not Cloudron single sign-on. Create the first account after installation.
To build the package from this checkout instead:
cloudron install --build-arg APP_COMMIT=$(git rev-parse --short HEAD)
The CLI builds the package on the server using Dockerfile.cloudron. The manifest requires Cloudron 10.0.0 for consistent database backup hooks. Allow space for a second database copy. The installation guide covers the package, the catalogue, and aliases.
Before inviting writers #
- Claim the instance. Sign-up closes as you claim it; open it again on Instance if writers should register themselves.
- Set the public address and proxy configuration, then restart the app.
- If you want reset email, configure mail and test a reset for your own account.
- Take a backup, copy it off the machine, and run a restore drill.
- Make sure that
/api/healthreturns the expected version and commit.
The Instance page shows the build, database path, migration level, recovery history, and latest restore drill. It also manages the instance name, sign-up, image preservation, and accounts.
Configuration #
These defaults apply to server.js unless the deployment overrides them. Compose and Cloudron set their own database paths. Restart after changing runtime values.
| Variable | Default | Meaning |
|---|---|---|
DATABASE_URL |
data/dev.db |
SQLite file, with an optional file: prefix. Relative to the process working directory. |
ORIGIN |
Empty | Public origin: scheme, host, and optional port. Leave empty to accept the request's address. |
INSTANCE_ORIGIN |
Empty | Advertised address for passkeys and reset links when ORIGIN is empty. |
TRUST_PROXY |
0 |
Set 1 only behind a trusted proxy that overwrites forwarding headers. The entry point then takes the client address from X-Forwarded-For. |
BETTER_AUTH_SECRET |
Generated by container startup | Persistent cookie-signing secret. Bare Node must supply it or sessions end on restart. |
HOST |
0.0.0.0 |
Listen address. The systemd example uses 127.0.0.1. |
PORT |
3000 |
Listen port inside the app process. |
BODY_SIZE_LIMIT |
101M |
The adapter's ceiling for any request body. One MiB above the 100 MiB import file limit; every other route is capped below it. |
ADDRESS_HEADER |
Unset, or x-forwarded-for with TRUST_PROXY=1 |
Header the entry point and adapter-node read the client address from. The entry point overwrites it, so a client cannot set it. |
XFF_DEPTH |
1 with TRUST_PROXY=1 |
Trusted proxy entries counted back from the right of X-Forwarded-For. The entry point reads it; the adapter receives one address. |
SMTP_HOST |
Empty | SMTP server for password resets. |
SMTP_PORT |
587 |
SMTP port. Use 465 with SMTP_SECURE=true. |
SMTP_SECURE |
false |
true or 1 for TLS from the first byte. Otherwise the transport can use STARTTLS. |
SMTP_USER |
Empty | Relay username. Authentication requires both user and password. |
SMTP_PASSWORD |
Empty | Relay password. |
MAIL_FROM |
Empty | Sender line. Reset mail needs this, SMTP_HOST, and a declared public address. |
FABLEWRIGHT_ALLOW_NEWER_SCHEMA |
0 |
Emergency override for the older-build refusal. Read the rollback procedure first. |
APP_COMMIT |
Checkout commit at build time, otherwise unknown |
Embedded build identity. Pass it explicitly when building an image. |
FABLEWRIGHT_TAG |
Tag in docker-compose.yml |
Compose image selection. Not an app variable. |
One MiB is 1,048,576 bytes. The import UI calls 100 MiB “100 MB”. The default request limit is 101M, so a full-size file fits with its multipart headers. A reverse proxy can still impose a lower limit.
APP_COMMIT is a build value. Changing it at runtime does not change the version or commit embedded in the app. The entry point and operations tool also read it for their own output.
Compose reads .env to substitute values into its YAML. It does not pass every value to the container. SMTP values need an override file or explicit environment entries. The installation guide provides an example.
For one public address, set ORIGIN. For several domains, leave it empty and set INSTANCE_ORIGIN to the primary address. Passkeys work there, while aliases keep password sign-in. Reset email also uses that declared address.
Behind a proxy, ORIGIN supplies the scheme but not the client address. Set TRUST_PROXY=1 as well if you need the forwarded client address for sign-in limits. Block direct access to the app port. The operations guide explains the trust rules.
Back up #
Recovery history and project archives do not replace an instance backup. A full backup holds the database, uploads, and auth-secret file when present. Keep an environment-supplied secret separately.
For the supplied Compose deployment:
docker compose exec fablewright node scripts/ops.mjs backup
docker compose exec fablewright node scripts/ops.mjs drill
For bare Node, run node scripts/ops.mjs backup --database /path/to/fablewright.db as the service user. The tool can copy a running database and keeps eight backups by default. Copy the resulting directory off the machine.
The operations guide covers schedules, verification, stopped-app restores, upgrades, rollback, account recovery, and moving an instance. Stop the app before restoring. Cloudron restores use the platform's backup workflow.
Develop #
Use Node 24 or newer and pnpm 12.21.0 or newer:
mkdir -p .agents/skills
pnpm install --frozen-lockfile
cp .env.example .env
pnpm dev
The example environment uses http://localhost:5173. The stack is SvelteKit 3, Svelte 5, TypeScript, TipTap, better-auth, and SQLite through node:sqlite and Drizzle.
Run pnpm check, pnpm lint, pnpm test:unit --run, and pnpm test:e2e before submitting code. The end-to-end suite runs a production build on port 4173. It deletes .test-data/e2e/, which holds its database, uploads, and drill records. Never point it at real writing.
The development guide has the command reference, code map, test isolation rules, migration workflow, coverage, mutation testing, and release checklist. CONTRIBUTING.md explains bug reports and patches.
Documentation #
| Document | For |
|---|---|
| Use Fablewright | Writers. Also served at /help. |
| Install Fablewright | A first deployment with Compose, Node, or Cloudron. |
| Import and export | Moving a manuscript and choosing a format. |
| Operate an instance | Backups, upgrades, accounts, storage, and monitoring. |
| Recover project work | Deleted work, earlier versions, and project copies. |
| Invitations and secret links | Project permissions and review. |
| Troubleshooting | Writer and operator failures by symptom. |
| Develop Fablewright | Contributors and maintainers. |
| Security model | Stored data, privacy, and trust boundaries. |
| Landmines | Maintainers changing a feature. |
| Product | Scope and commitments. |
| Design | The Plotting Floor visual system and its measured limits. |
| Changelog | Changes in each release. |
| Contributing | Bug reports, patches, and reviews. |
| Security policy | Private vulnerability reports. |
Security #
Use HTTPS outside localhost. Protect the data directory, backups, and logs. Logs can contain password-reset links, and project archives include deleted work and earlier drafts.
Report vulnerabilities to the lead maintainer, not through a public issue. Read the security policy for report details and the security model before hosting other people's work.
AI Disclosure #
This section is here purely to avoid future annoyance. Yes, AI was used, and will continue to be used, in coding Fablewright. If that is a problem for you, please do not use or otherwise interact with Fablewright or this repository. Thank you!
License #
Mutualist License v1.3, Short ID MutuaL-1.3. See LICENSE.md for the terms.
The bundled fonts use the SIL Open Font License 1.1. See the font notices for their sources.
Project home: https://tangled.org/katsuricata.com/Fablewright. Original copyright holder: Kat Suricata.



