Self-hosted service
shuaiplus/inkstone avatar
shuaiplus/inkstone

Inkstone: self-hosted means your Cloudflare account, and the end-to-end test deletes data on a fixed port

A self-hosted Markdown notebook that runs entirely on Cloudflare Workers.

1,187 stars1,092 forksTypeScriptNOASSERTION

At a glance

What is it?
A Markdown notebook that runs entirely on Cloudflare Workers, with its own database, attachment store, OAuth provider and sync durable objects. The deployment path goes through a GitHub fork and a Cloudflare dashboard, two attachment backends mean two parallel configuration worlds, and the end-to-end script creates, changes and deletes data at a hard-coded local address.
Who is it for?
Use Inkstone if you want plain Markdown files in a database you control and you are already willing to run software on Cloudflare's edge, because that is what self-hosted means here rather than a server in your house. Five things to know first.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 39 days ago.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shuaiplus/inkstone1,187 ★ · +446
Star history
Repository2026-09-112026-11-15
shuaiplus/inkstone7411.2k

446 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Self-hosted here means a Cloudflare account, not a machine you own

The summary calls it a self-hosted application and says the deployer retains control of the database, the attachments and the runtime environment. The deployment procedure shows what that means in practice. You fork the repository to your own GitHub account, open the Cloudflare dashboard, choose the option that continues with GitHub, and pick your fork. The result is a worker on Cloudflare's edge with a database in your Cloudflare account, an attachment store in your account, and OAuth state in a key-value namespace you create. Nothing runs on infrastructure you administer in the conventional sense, and the notes are in Cloudflare's database rather than on a disk you can mount. The word is accurate about who controls the data and misleading to anyone who reads it as running on their own server.

Two attachment backends means two parallel configuration worlds

Attachments and avatars live in either an object store or a key-value namespace, chosen by a binding name, and the choice is made at deploy time rather than at runtime. The instructions reflect that: the R2 path uses the standard build and deploy commands, and using the key-value path means changing the deploy command to a different npm script. The repository carries two top-level configuration files for this, and the package manifest carries parallel scripts for each world: separate build, deploy, dry-run deploy and type generation commands. Three separate TypeScript project configurations exist for the client, the build tooling and the worker, so the type check runs as a project-reference build. Nothing in the interface tells a deployer which backend they ended up with, and the binding name is the only place the difference shows.

The end-to-end script is destructive and addresses a fixed port

One verification command is documented with an explicit warning attached, and the warning is the most useful sentence in the development section. The end-to-end script creates, changes and deletes data, and it does so against one fixed local address, with the instruction to run it only against a fresh local state dedicated to testing. Nothing binds that address to the development server, nothing checks that the port belongs to a throwaway instance, and the script is a single command away from anyone who has the repository checked out. The rest of the verification surface is safer and more conventional: a unit suite, a type check, a locale parity check between the English and Chinese resources, a source-comment policy check, and a separate cross-module regression directory.

A backup includes the trash and excludes every credential

Two export paths exist and they are not the same shape. A JSON export preserves the older structured notebook format for re-import, which is a migration path rather than a readable archive. The ZIP export and the remote backups share one verified Markdown snapshot format, and that snapshot includes readable notes, archived notes, trashed notes, attachments, and a completion marker, with duplicate attachment content stored once per snapshot. Large restores are handled by selecting the backup folder rather than loading one whole archive into memory. What never leaves the system is listed just as precisely: login passwords, active sessions, share passwords, and the credentials for the backup service itself. Public share links can still carry an access password and an expiry date, and neither of those travels in the archive.

The notebook is a model context protocol server with a write path

One row of the feature table is devoted to agent access, and it is more than a read surface. There is a private remote endpoint speaking the protocol, an OAuth flow with PKCE, revocable API keys with a distinctive prefix, a standard search tool and a standard fetch tool, and then three qualifiers that matter: reads are bounded, writes are checked against a revision so a stale write is refused rather than applied, and the trash has a separate permission from the rest of the write surface. Grants are managed per account. The token material for that flow lives in its own key-value namespace, and the page is careful to say that note bodies are not stored there. So an agent connected to this notebook can read bounded slices and make revision-checked edits, and the permissions are split finely enough that you can grant editing without granting deletion.

One tab polls, and the rest wait for it

The reliability row is the longest in the table and it describes a synchronisation design rather than a feature list. Writes happen locally first and roll back if the server refuses, an offline queue holds pending changes in browser storage, stale syncs are detected rather than merged, and conflicts are kept as copies instead of being resolved. Realtime notification between active clients runs through a durable object, with an elected-tab polling fallback when that channel is not there. Elected means one tab takes the polling duty rather than all of them, which is the right call for a notebook open in six windows and a subtle failure mode if the elected tab goes away. A second durable object exists solely to hold the key that encrypts backup credentials, isolated from everything else.

The public demo is a static build that resets itself

The repository's homepage field points at a static demo hosted on the pages domain, not at the application. That demo is a separate build mode with its own configuration file and its own deploy script, and it is browser only, with no worker behind it. Its data story is stated in the same paragraph that introduces the starter notes: every new account receives two notes, one in Chinese and one in English, and the browser-only demo reuses that content, so refreshing the page restores those two starter notes rather than loading a separate demo set. So a visitor to the homepage sees a notebook that appears to work, contains exactly two notes, and forgets everything on refresh. The real application is the worker URL that appears at the end of the deployment steps.

The licence is stated in two places and recorded in neither

The page header links the licence file and names a specific variant of the GNU Lesser General Public License, version three, only. The licence section says the same thing, and the package manifest carries the same identifier in its licence field with the only variant rather than the or-later form, which matters if you ever relicense a derived work. A licence file is present at the root. The one place the licence is not recorded is the repository's own metadata, which carries no recognised identifier at all. That gap is administrative rather than substantive, since the file and the manifest agree, but it is the kind of thing a package index reads from the metadata rather than from your readme.

Editorial conclusion

Use Inkstone if you want plain Markdown files in a database you control and you are already willing to run software on Cloudflare's edge, because that is what self-hosted means here rather than a server in your house. Five things to know first. Decide which attachment backend you are deploying, since the object store and the key-value store are separate configurations with separate build, deploy, verify and type generation commands, and picking the wrong script is the easy mistake. Never run the end-to-end script against a port you have not just emptied, because it creates, changes and deletes and it addresses a fixed local port. Read what a backup contains, which is notes including archived and trashed ones plus attachments, and read what it excludes, which is passwords, sessions, share passwords and backup credentials. If you connect an agent, note that the notebook exposes a remote model context protocol surface with a search tool, a fetch tool, bounded reads and revision-safe writes, and that trash has its own permission. And set a backup target before you trust it with anything you would miss.

Frequently asked questions

Where does Inkstone actually run?

On Cloudflare Workers, with a database, attachment store and OAuth namespace in the deployer's Cloudflare account. Deployment goes through a fork in the deployer's own GitHub account and the Cloudflare dashboard, so the data is the deployer's rather than a server they administer.

What does the Inkstone end-to-end test do?

It creates, changes and deletes data at a fixed local address. The page warns to run it only against a fresh local state dedicated to testing, and the address is not bound to the development server automatically.

What is included in an Inkstone backup?

A verified Markdown snapshot containing readable notes, archived and trashed notes, and attachments, with duplicate attachment content stored once. Login passwords, active sessions, share passwords and backup service credentials are excluded.

Can an AI agent write to an Inkstone notebook?

Yes, through a private remote endpoint with a search tool, a fetch tool, bounded reads, revision-checked writes and a separate permission for the trash. Access uses OAuth with PKCE and revocable API keys, managed per account.

What licence is Inkstone released under?

The GNU Lesser General Public License version three, only, named in the page header, in the licence section and in the package manifest. The repository metadata itself carries no recognised licence identifier.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. shuaiplus/inkstone on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shuaiplus-inkstone.svg)](https://hysenlabs.com/projects/shuaiplus-inkstone)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shuaiplus-inkstone.svg)](https://hysenlabs.com/projects/shuaiplus-inkstone)

Was this useful?