Inkstone: A Self-Hosted Markdown Notebook That Runs on Cloudflare Workers

What Inkstone Is and Who Deploys It

Inkstone is a self-hosted application that brings together a Markdown editor, a note organizer, and a sync engine into a single Cloudflare Workers deployment. The deployer owns the database, the attachment storage, and the runtime. Notes stay as plain Markdown files internally; the application layers search indexing, bidirectional links, and offline capability on top of that plaintext foundation.

The target user is a developer or small team that wants Obsidian-style note organization with cross-device sync but without depending on a commercial sync service. The application serves a browser UI, so any device with a modern browser can access the notes. Two deployment modes exist: R2 mode for binary attachment storage, and KV mode for environments where R2 is not preferred. The distinction matters because R2 and Workers KV have different pricing and operational characteristics.

Cloudflare Infrastructure: D1, R2, Durable Objects, and Browser Cache

Inkstone uses four layers of Cloudflare storage. Cloudflare D1 holds accounts, notes, folders, tags, settings, version history, shares, full-text search indexes, per-account AI embeddings, and background indexing queues. This is the primary database; D1 provides the FTS5 full-text index with Chinese character indexing built in. R2, or optionally Workers KV, stores attachment and avatar binaries through the FILES or FILES_KV binding.

Two Durable Objects provide coordination. SyncHub sends realtime change notifications between active browser sessions. CredentialVault provides isolated storage for the key used to encrypt backup credentials, keeping backup credentials isolated from the rest of the application state.

The browser also plays a storage role. IndexedDB caches notes locally and holds a pending write queue for offline edits. When the network returns, the queue flushes with optimistic concurrency control: immediate local mutations happen on the client, with rollback if the server disagrees. Conflicting edits create conflict copies rather than silently losing one version.

Deploying from a GitHub Fork to Cloudflare Pages

The README describes a four-step deployment. Fork the repository to your GitHub account, then open Cloudflare Workers and Pages and select your fork. Set the build command and deploy command:

npm run build
npm run deploy

For KV mode, change the deploy command to `npm run deploy:kv`. After deployment completes, open the generated Workers URL. Existing databases upgrade automatically through versioned, idempotent migrations; the README notes that you should keep a current backup before any update.

For local development:

npm run dev

This starts both the local Worker and the Vite frontend. The KV variant:

npm run dev:kv

The unit test suite runs with:

npm run test:unit

The end-to-end verification script at scripts/e2e.mjs tests against a live local instance; it creates, changes, and deletes data at http://localhost:7712 and should only run against a fresh local state.

The Editor and Note Organization Surface

The writing interface is built on CodeMirror 6. Notes have independently editable titles, and the workspace supports two-note editor groups, meaning two notes can be open side by side with independent scroll sync. Layout switches between editor, split, and preview per group. Focus mode and typewriter mode let writers minimize distractions. Autosave runs continuously, and a version history captures prior states.

Markdown rendering covers GitHub Flavored Markdown tables and task lists, footnotes, Obsidian-style comments, WikiLinks, block IDs, callouts, details blocks, tabs, math, Mermaid diagrams, and PrismJS syntax highlighting. Front Matter is recognized and indexed.

Organization uses nested folders with drag-and-drop ordering, inline tags, favorites, pinning, archive, and trash. The relationship graph visualizes bidirectional links across the note collection. Public sharing supports optional access passwords and expiration dates on shared links. The application ships with English and Simplified Chinese localization.

Full-Text Search, Semantic AI, and MCP Access

Search uses D1's FTS5 engine with Chinese character indexing, filters, recent note access, and command-palette navigation. An optional semantic and hybrid search path uses Workers AI embedding generation stored per account in D1. Deployments where Workers AI is not available fall back to lexical search without any configuration change required.

The MCP server exposes standard search and fetch tools over OAuth 2.1 with PKCE. API keys use the ink_... prefix format and are revocable per-account through the grant management interface. Reads are bounded and writes are revision-safe; a separate trash permission controls access to archived content. The MCP server allows coding agents and AI tools to interact with the note collection through a standard protocol rather than through screen scraping or unofficial APIs.

Where Inkstone's Design Has Costs

Inkstone depends entirely on Cloudflare's paid services. D1, R2, Durable Objects, and Workers AI each have free tiers, but a production deployment with active users will incur billing. The Durable Object for realtime sync (SyncHub) charges for request and storage duration. Semantic search with Workers AI embeddings adds per-query costs.

The LGPL-3.0-only license requires any modifications to the Inkstone source code to remain open-source. Using an unmodified deployment as a personal note server does not trigger this requirement. Organizations that need to modify and run the code privately would need to negotiate a separate license or accept the copyleft terms.

The offline write queue protects against network interruptions, but conflict resolution creates conflict copies rather than merging. In a multi-user scenario with many concurrent edits to the same note, conflict copy accumulation requires manual cleanup. The backup system does not include login passwords, active sessions, or backup service credentials in its exports, so a restored instance requires reconfiguration of those elements.

Obsidian as a Desktop-First Alternative

Obsidian is a desktop and mobile note-taking application with a local vault stored as plain Markdown files. Unlike Inkstone, Obsidian does not require a server or a cloud account: notes live on your device's filesystem, and plugins are installed locally. Cross-device sync requires either a paid Obsidian Sync subscription or setting up a third-party sync service separately.

The practical difference is deployment model. Inkstone runs in any browser and syncs across devices through your own Cloudflare account, with no local application to install. Obsidian is an installed application with local-first storage; sync is an add-on rather than the default. For teams who want shared access to a note collection from any browser without managing a desktop application, Inkstone fits better. For individuals who prefer keeping notes off any cloud provider and want a rich plugin ecosystem, Obsidian is the more established choice.

Inkstone had its last push on September 25, 2026, and released v0.8.0 on September 14, 2026, which added live preview and a mobile-first workspace redesign.

Editorial conclusion

Inkstone is the right fit for a developer or small team comfortable with Cloudflare who wants a personal knowledge base under their own account, with offline capability and a real search index. It is not the right choice for anyone who needs to avoid a Cloudflare dependency, requires per-document access control beyond basic auth, or wants to use a standard desktop editor. The LGPL-3.0-only license means modifications to Inkstone itself must stay open-source, but using it as-is to host your own notes does not trigger that requirement. Before deploying, confirm that the Cloudflare account has D1, R2, Durable Objects, and Workers AI all enabled, since the deployment uses all four.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. shuaiplus/inkstone on GitHub