Inkstone is the Cloudflare-native Markdown notebook I wanted to inspect after looking at Monolith, EmDash, FlareMo, and Cloudflarebase.
Those projects mostly orbit publishing, CMS workflows, Firebase-like app backends, or Memos-style capture. Inkstone is much closer to the thing many of us actually live inside every day: a private Markdown notebook with folders, backlinks, search, attachments, history, public shares, backups, and a PWA that still behaves sensibly when the network drops.
The important caveat is also clear from the start. Inkstone is self-hosted, but not as a single Docker Compose service. It is built for Cloudflare Workers, D1, R2 or KV, Durable Objects, Workers KV, and optional Workers AI.
What is Inkstone?
Inkstone is an LGPL-3.0 Markdown notebook that runs on Cloudflare Workers.
The repository describes it as:
A self-hosted Markdown notebook that runs entirely on Cloudflare Workers.
The feature list is unusually deep for a Workers app:
- CodeMirror 6 Markdown editor;
- split editor/preview layouts;
- two-note editor groups;
- synchronized scrolling;
- outline, focus mode, and typewriter mode;
- autosave and version history;
- GitHub Flavored Markdown, tables, task lists, footnotes, math, Mermaid, callouts, details, tabs, and front matter;
- WikiLinks, backlinks, block IDs, block references, embeds, and a graph view;
- nested folders, tags, favorites, pinning, archive, and trash;
- D1 full-text search with Chinese indexing;
- optional semantic and hybrid search with Workers AI;
- public share links with optional passwords and expirations;
- PWA launch, local cache, offline write queue, conflict copies, and stale-sync protection;
- JSON/ZIP export, attachment export, and WebDAV/S3 backups;
- private remote MCP with OAuth 2.1 PKCE and revocable
ink_...API keys.
That makes Inkstone more than a “notes CRUD app”. It is closer to a Cloudflare-native Obsidian-ish web notebook, although its source of truth is not a local folder of files.
Architecture Overview
The clean mental model:
React PWA -> Hono Worker API -> D1 notes database
|
+-> R2 or KV attachments
+-> Durable Objects for sync and credential encryption
+-> OAUTH_KV for MCP OAuth state
+-> Workers AI for optional embeddings
| Layer | Inkstone Uses |
|---|---|
| Frontend | React 19, Vite 8, TypeScript |
| Editor | CodeMirror 6 |
| Markdown | markdown-it plugins, KaTeX, Mermaid, PrismJS |
| API | Hono on Cloudflare Workers |
| Primary database | Cloudflare D1 |
| Attachment storage | R2 default mode, or Workers KV mode |
| OAuth/MCP state | Workers KV OAUTH_KV |
| Realtime/sync | Durable Object SyncHub |
| Secret handling | Durable Object CredentialVault |
| Optional AI | Workers AI embeddings |
| Browser cache | IndexedDB |
D1 stores the main notebook model: users, notes, folders, tags, versions, shares, settings, search indexes, backup metadata, and indexing queues.
Attachments and avatars go to R2 in the default deployment. There is also a KV storage mode through wrangler.kv.toml, which can be useful for smaller or simpler deployments.
The Important Markdown Detail
Inkstone says notes remain plain Markdown text, and that is true in the portability sense: exports and backups are readable Markdown rather than an opaque proprietary document format.
But the running app is still database-backed.
live app source of truth = D1
portable content format = Markdown
export/backup format = readable Markdown plus metadata and attachments
That distinction matters if your personal target is a Git-backed Astro or Hugo workflow. Inkstone gives useful ideas for the editor, backlinks, offline queue, backups, and Markdown extensions, but it is not already a “commit .md files to Git on publish” system.
Deployment Path
The upstream deployment path is Cloudflare Workers & Pages connected to a GitHub fork.
For the default R2-backed build:
npm install
npm run build
npm run deploy
For KV attachment mode:
npm run build:kv
npm run deploy:kv
For local development:
npm run dev
npm run dev:kv
npm run dev:demo
The Vite dev server is configured on port 7712, and preview is configured on 7713.
Cloudflare Resources You Need
For the full app, plan for these Cloudflare resources:
| Resource | Binding | What It Does |
|---|---|---|
| D1 | DB |
Accounts, notes, folders, tags, versions, shares, search/index data, backup metadata |
| R2 | FILES |
Attachments and stored avatars in default mode |
| Workers KV | FILES_KV |
Alternative attachment storage in KV mode |
| Workers KV | OAUTH_KV |
MCP OAuth client registrations, authorization codes, tokens, refresh tokens, and grants |
| Durable Object | SYNC_HUB |
Realtime sync notifications and polling fallback coordination |
| Durable Object | CREDENTIAL_VAULT |
Encryption/decryption service for backup credentials and TOTP secrets |
| Workers AI | AI |
Optional semantic embeddings and hybrid search |
| Workers Static Assets | ASSETS |
The built React frontend |
| Cron triggers | schedules | Scheduled background work, including backup/indexing tasks |
If you deploy manually or from CI, expect to configure a Cloudflare account ID and API token with permissions for Workers, D1, R2 or KV, Durable Objects, and Workers AI if you enable semantic search.
If you use the Cloudflare dashboard’s GitHub integration, some of that is handled interactively, but the underlying resources still exist.
Field Note: Local Build
I tested the repository from commit ce0053dacac3f577aa371c0ce2c5cc81dfed06c0.
The checked-in package-lock.json contains many resolved URLs pointing at registry.npmmirror.com. In this environment, npm ci failed with EALLOWREMOTE because npm was configured not to fetch those remote tarballs.
This install path worked for source validation:
npx -y -p node@24 -p npm@latest bash -lc 'npm install --package-lock=false --ignore-scripts'
npx -y -p node@24 -p npm@latest bash -lc 'npm run build'
npx -y -p node@24 -p npm@latest bash -lc 'npm run typecheck'
The build and typecheck passed with Node v24.21.0 and npm 12.2.0.
Two practical notes:
- npm reported 7 dependency vulnerabilities during install;
- Vite warned about large chunks, which is not surprising for a notebook that bundles CodeMirror, Mermaid, KaTeX, PrismJS, and graph/editor tooling.
Where Inkstone Fits
| Project | Best Use |
|---|---|
| Inkstone | Cloudflare-native Markdown notebook |
| FlareMo | Memos-style knowledge base, tasks, teams, MCP, AI memory |
| Monolith | Cloudflare-native blog CMS |
| EmDash | Astro CMS with database-backed publishing |
| Cloudflarebase | Firebase-like backend on Cloudflare |
| Cloudflare Workers, D1, KV, and R2 | The broader serverless stack pattern |
I would pick Inkstone if the priority is writing and organizing personal Markdown notes inside a browser, with Cloudflare handling the infrastructure.
I would not pick it as-is if the hard requirement is “Markdown files in Git are the only source of truth.”
FAQ
Can Inkstone be self-hosted in a homelab with Docker?
Not as the production architecture ships today.
Inkstone is self-hosted by deploying it into your own Cloudflare account. The runtime expects Cloudflare Workers, D1, R2 or KV, Durable Objects, Workers KV, and optional Workers AI.
You can develop it locally with Vite and Wrangler, and the demo mode can run like a browser-only evaluation build. But a single local Docker Compose file would not reproduce the full production app unless someone wrote compatibility layers for D1, R2/KV, Durable Objects, OAuth KV state, cron behavior, and Workers AI.
Does Inkstone use Better Auth?
No. Inkstone implements its own account system.
The first registered account becomes the owner. Registration is closed after that unless the owner opens it again in settings. Passwords are stored as scrypt hashes, sessions are stored in D1, and TOTP is supported.
This is different from projects like FlareMo, Feedlog, and Cloudflarebase, where Better Auth was part of the auth story.
What does the PWA actually do?
Inkstone’s PWA behavior is more serious than just adding a manifest.
The service worker caches the app shell and built assets so the notebook can launch offline. The browser keeps cached notebook state in IndexedDB, and the client has an offline write queue with optimistic concurrency, stale-sync protection, rollback handling, and conflict copies.
Dynamic routes remain network-only. API calls, OAuth, MCP, authorization, and well-known endpoints still need the Worker.
That is the right tradeoff for a private web notebook: fast offline access and queued edits, without pretending that authentication and server coordination can happen without the server.
Does Inkstone store real Markdown files?
Not as live files in a Git repository.
Inkstone keeps note content as Markdown text, but the running app stores that content in D1. Exports and backups can produce readable Markdown and attachments, which is excellent for portability.
If you want a Git-centered Astro site, you would still need a layer that turns notebook saves into .md commits, pull requests, or CI-triggering file updates.
Could Inkstone ideas help a Git-backed Astro editor?
Yes, quite a lot.
The strongest ideas to borrow are:
- CodeMirror-based Markdown editing with preview modes;
- WikiLinks, backlinks, block references, and embeds;
- offline write queue and conflict copies;
- readable Markdown exports;
- WebDAV/S3 backup thinking;
- clear network-only boundaries for auth/API routes;
- MCP with scoped permissions and revocable API keys.
The part I would not copy directly is D1 as the ultimate publishing source of truth if your desired architecture is:
authenticated editor -> Markdown commit -> CI build -> static Astro on Cloudflare Pages
For that model, the commit is the publish event. R2 can store photos, while Git stores Markdown and content history.
What Cloudflare permissions or API keys are required?
For dashboard deployment, the GitHub integration can guide you through the resource creation flow.
For CLI or CI deployment, expect:
CLOUDFLARE_ACCOUNT_ID;CLOUDFLARE_API_TOKEN;- permissions for Workers deployment;
- D1 edit permissions;
- R2 edit permissions for default mode;
- KV edit permissions for
OAUTH_KV, and alsoFILES_KVif using KV attachment mode; - Durable Object migration/deployment permissions through Workers;
- Workers AI access if semantic search is enabled;
- DNS or route permissions only if you attach a custom domain.
Inside Inkstone itself, users configure their own app accounts. Backup targets may require WebDAV credentials or S3-compatible access keys, which Inkstone encrypts through the CredentialVault Durable Object.
What is the difference between R2 mode and KV mode?
R2 mode is the default and better fit for attachments, avatars, and larger binary objects.
KV mode replaces the attachment bucket with Workers KV through FILES_KV. It can be simpler for small deployments, but KV is still a key-value store, not an object-storage system designed around larger file workloads.
For a serious notebook with images, PDFs, or exports, I would start with R2.
Does Inkstone need Workers AI?
No for the core notebook.
D1 full-text search provides the normal keyword search path. Workers AI is optional and adds embeddings for semantic or hybrid search.
That makes the AI layer an enhancement, not a blocker for writing, folders, backlinks, public shares, exports, or backups.
How does Inkstone compare with Obsidian or Logseq?
Obsidian and Logseq are local-first desktop/mobile knowledge tools where files are commonly the center of gravity.
Inkstone is a browser notebook deployed on Cloudflare. It gives you a web app, accounts, sharing, PWA behavior, remote MCP, backups, and Cloudflare-managed infrastructure, but D1 is the live database.
So the decision is not just features. It is source-of-truth philosophy:
Obsidian/Logseq style = files first
Inkstone style = Cloudflare app first, Markdown-portable
Conclusion
Inkstone is one of the strongest Cloudflare-native personal knowledge apps I have looked at so far.
It is not a homelab Docker app, and it is not Git-backed publishing out of the box. But as a Workers-based Markdown notebook with serious PWA behavior, D1 search, optional AI search, public sharing, MCP access, and readable Markdown backups, it is a very useful reference point for where Cloudflare self-hosting is heading.
Comments