Sink docs GitHub

Docs

Everything you need to run Sink on your own server, and to bend it to how you work. Want a look first? Try the demo; it runs in your browser.

Install

You need Docker, a domain or LAN address for Sink, and an OpenID Connect sign-in provider.

mkdir sink && cd sink
curl -O https://raw.githubusercontent.com/heycastawhat/sink/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/heycastawhat/sink/main/.env.example
# edit .env: SINK_PUBLIC_URLS, the SINK_OIDC_* settings,
# SINK_OIDC_ALLOWED_USERS and SINK_TIMEZONE
docker compose up -d

Sink listens on port 8787. Put it behind HTTPS (Caddy, Traefik, nginx, a Cloudflare tunnel or Tailscale) before using it from outside your network; plain http is fine on a LAN.

Where things live

FolderWhat's in it
./notesYour notes, one .md file each. Point it at an existing folder or Obsidian vault by changing the ./notes:/notes line in docker-compose.yml.
./dataThe database: search index, sign-ins, settings, daily snapshots. Keep it on local disk; SQLite on a network share can corrupt.
./pluginsPlugins you add, one folder each.

If your files belong to a user other than 1000:1000, set PUID and PGID in .env.

Updating

docker compose pull && docker compose up -d

Sign-in

Sink doesn't store passwords. It signs you in through an OpenID Connect provider, so you get passkeys, 2FA and everything else your provider already does. Create a client (an "OAuth2 / OpenID application") there with:

  • Redirect URI: https://<your Sink address>/api/auth/oidc/callback, one per address in SINK_PUBLIC_URLS
  • Scopes: openid email profile
  • Client type: confidential (with a secret), or public (PKCE only; leave SINK_OIDC_CLIENT_SECRET empty)
ProviderIssuer URL looks like
Pocket IDhttps://id.example.com (simplest to self-host: passkeys only)
authentikhttps://auth.example.com/application/o/<app slug>/
Autheliahttps://auth.example.com
Keycloakhttps://kc.example.com/realms/<realm>
Googlehttps://accounts.google.com

Who's allowed in

Sink won't start until you say who can sign in. Each entry in SINK_OIDC_ALLOWED_USERS (comma-separated) matches one thing:

  • you@example.com (or email:you@example.com): your email, if the provider says it's verified
  • user:you: your username at the provider. Only use this if people can't pick their own usernames there
  • sub:1234… (or anything else): the provider's fixed ID for your account

SINK_OIDC_ALLOWED_GROUPS works too, for groups an admin assigns. Once you're in, you can add more people from Settings; see People and accounts.

Shared provider? If other people can sign in to your provider (Google, or a family authentik), never set SINK_OIDC_ALLOW_ANY_USER. It lets in anyone the provider signs in.

People and accounts

One Sink can hold several people's notes. Everyone you let in gets their own private notes, todos, trash and history; nobody can see anyone else's.

  • The owner is whoever was using Sink first (or the first to sign in). Their notes are the folder mounted at /notes, and email in and plugins work on them.
  • Everyone else gets a notes folder and database of their own under SINK_USERS_DIR (default data/users/<id>/).

Adding people

Settings → People takes the same kinds of entries as SINK_OIDC_ALLOWED_USERS: an email or user:name. Removing someone there signs them out.

For someone without an account at your sign-in provider, Invite someone with a passkey makes a link that works once, for 7 days. They open it, make a passkey, and sign in with that from then on, on the web and in the Android app.

Invite on the right address. A passkey belongs to the address it was made on, so send the invite from the address they'll use Sink on.

Settings

Everything goes in .env. Restart with docker compose up -d after changing it.

SettingWhat it does
SINK_PUBLIC_URLSEvery address Sink is reached on, main one first, comma-separated, no trailing slash. Sign-in only redirects back to these, and browser requests from anywhere else are refused.
SINK_OIDC_ISSUERThe provider's base URL (the one serving /.well-known/openid-configuration).
SINK_OIDC_CLIENT_ID
SINK_OIDC_CLIENT_SECRET
The client you made. Leave the secret empty for a public client.
SINK_OIDC_ALLOWED_USERS
SINK_OIDC_ALLOWED_GROUPS
Who may sign in, comma-separated. More people can be added in Settings → People. See Sign-in.
SINK_OIDC_NAMEShown on the button: "Sign in with Pocket ID".
SINK_TIMEZONEYour time zone, for reminders and note dates. Pacific/Auckland, Europe/London…
SINK_USERS_DIRWhere everyone but the owner keeps their notes and database. Default data/users.
SINK_NOTES_SCAN_SECONDSHow often to rescan the notes folder for edits made outside Sink. Default 30.
PUID / PGIDUser and group Sink runs as. Default 1000.
SINK_TRASH_DAYSDays deleted notes stay in .trash/. Default 30; 0 keeps them forever.
SINK_BACKUP_KEEPDays of database snapshots kept in data/backups. Default 7; 0 turns them off.
SINK_MAX_UPLOAD_MBLargest attachment you can upload.
SINK_PLUGINS_DISABLEDBuilt-in or installed plugins to turn off, by id.
SINK_IMAP_*Email in. See Email in.

Android app

Download the APK from the latest release, allow installs from your browser, open it and enter your Sink address. The app checks for a new version once a day (or from Settings) and offers to install it.

Or let Obtainium keep it updated: add Sink to Obtainium, or add https://github.com/heycastawhat/sink by hand.

Notes in the Android app
Todos in the Android app
A note open in the Android app

Signing in

Type your Sink address and sign in through your provider, or skip the typing: in Settings on a signed-in browser, show a sign-in QR code (it works once, for five minutes) and scan it with "Scan sign-in code" in the app.

What it does

  • Notes and Todos in a floating nav pill near your thumb. Pull up from the bottom of the grid for a new note; pull a note down from its top to close it.
  • Notes open in the same editor as the web, with a formatting bar above the keyboard; boards open in the same Excalidraw.
  • Swipe a card to pin or archive it; long-press it for quick actions.
  • On tablets and unfolded phones, the list sits beside the open note.
  • Edits made offline are kept on the phone and sent when you're back online. Changes from other devices show up live.
  • Reminders arrive as notifications with Done, 1 hour and Tomorrow buttons.
  • "New note" Quick Settings tile, and Share → Sink from any app: text becomes a note, photos and PDFs are attached to one, and a link on its own is clipped.

Web app on phones and tablets

On an iPhone, iPad, or anything without the Android app, use the web app. Install it (Add to Home Screen) and it runs like an app, and Share → Sink works from other apps on Android and ChromeOS.

Turn on Settings → Todo reminders to get reminders as notifications there too. It's per browser (on iPhone, only from the installed app), so turn it on only where you don't already have the Android app.

When a new version of Sink is deployed, the web app offers a reload.

Writing notes

Notes are markdown, shown as you'd read them: the symbols tuck away until your cursor is on that line. Type / at the start of a line for commands.

TypeGet
- [ ] or [] A todo
[[Note name]]A link that follows the note if it's renamed or moved; the other note lists it as a backlink
![[photo.jpg]]An embedded image (or paste or drop one in). A note's first image shows on its card.
![[Note]], ![[Note#Heading]]Another note, or one section of it, shown inline
```jsA code block, coloured by language
#tagA tag; search #tag to filter
> [!tip] TitleA callout
/tableA table you can edit in place
/templateThe contents of a note from your Templates/ folder
/mermaid, /mathA diagram or formula (built-in plugins)
/today, /date, /timeToday's date or the time

Under each note, Linked mentions lists the notes that link to it, and unlinked mentions finds notes that name it in plain text, with a button to turn each into a link. Paste a URL over selected text to link it.

Keyboard shortcuts

Ctrl K / ⌘ KJump to any note
NNew note
/Search notes
Ctrl S / ⌘ SSave now
EscClose the note

Pins, colours, folders

Pin and colour notes from the note's toolbar. Sink stores them as two frontmatter keys, pinned: true and color: yellow, so they travel with the file. Colours are red, orange, yellow, green, teal, blue, purple, pink, brown and gray. Folders are plain folders. Archive a note to keep it without it cluttering the grid.

Boards

New → Board makes an Excalidraw whiteboard, saved in the same format as Obsidian's Excalidraw plugin. Boards fill the pane, open as tabs, and work on Android too.

Layouts

On big screens, pick how notes open. Your choice follows you to every browser you sign in on; phones keep their own. Change it in Settings → Layout.

Classic layout
Classic Sidebar and a big sheet. Notes open full screen.
Keep layout
Keep Notes open in a window over the grid.
Split layout
Split Notes open in a pane beside the grid.
Tabs layout
Tabs Notes open in tabs, like a browser.

Todos

Every - [ ] in every note shows up on the Todos page, grouped into overdue, today, upcoming and someday. Ticking one there ticks it in the note. Dates use the Obsidian Tasks format, so they work in both apps.

- [ ] Pay rates 📅 2026-11-20 ⏫
- [ ] Water the monstera 🔁 every week 📅 2026-11-12
- [ ] Call the bank 📅 2026-11-13 (@2026-11-13 10:00)
- [x] Book flights ✅ 2026-11-04
MarkMeans
📅 dateDue. Reminds at 9am that day unless it has a time.
(@date 10:00)Remind at this time (Obsidian Reminder plugin format).
⏳ dateScheduled: when you plan to do it. Stands in for a due date.
🛫 dateStarts: hidden from the list until then.
🔁 every weekRepeats. Ticking it adds the next one with the dates moved on.
🔺 ⏫ 🔼 🔽 ⏬Priority, highest to lowest. Sorted and shown in the list.
✅ date, ❌ dateDone or cancelled, added for you.

Quick add

You don't need to type any of that. "Add a todo" reads a date, time or repeat off the end of what you write: call mum tomorrow 6pm, rates fri, bins every tuesday. Quick todos go in Todo.md.

Tick with Undo, tap a todo to edit it, or reschedule it in a tap. The Todos tab shows how many are overdue or due today.

Using it with Obsidian

Point ./notes at your vault, or sync the same folder with Syncthing, and both apps edit the same files. Sink writes standard markdown and understands frontmatter properties, [[wikilinks]], ![[embeds]], #tags, callouts, Tasks plugin dates, Reminder plugin times and Excalidraw plugin boards. Obsidian ignores Sink's pinned and color keys.

Deleted notes go to .trash/, like Obsidian's. Undo, or the Trash page, puts them back.

Edited in two places at once? Sink never overwrites. The other version is kept as a "(conflict …)" copy next to the note.

Obsidian sync plugin

If your vault lives on a server and you want Obsidian on a laptop or phone away from home, the Sink plugin for Obsidian syncs a local vault with Sink over the internet: notes, images and other files, both ways, on desktop and mobile. It syncs the account you sign in as.

cd obsidian && bun install && bun run build
mkdir -p "<your vault>/.obsidian/plugins/sink"
cp main.js manifest.json "<your vault>/.obsidian/plugins/sink/"

Turn it on in Community plugins, then in Settings → Sink enter your server address and press Sign in. Your browser signs you in and hands back to Obsidian.

  • Changes sync as you make them and as they happen on the server; offline edits go up when you're back.
  • If a note changed on both sides you get both: the server's keeps the name, yours is saved as Note (conflict 2026-11-02).md.
  • Renames move the note on the server (links follow); deletes go to Sink's trash.
  • A big batch of deletes is held back until you confirm it, in case one side is empty by mistake.
  • It never touches .obsidian/, .trash/ or other hidden folders.
  • Commands: Sync now, Open in Sink, Copy share link, Version history.

Sharing and publishing

Share links

The share button makes a link anyone can open without an account. Make it read-only, or let people with the link edit after giving their name. Visitors see the note's text and the images it embeds, never its properties. Stop sharing any time.

Public page

Pick a name in Settings → Public page, then use Share → Show on my public page on the notes you want listed at /public/<name>. It sets publish: true in the note, as Obsidian Publish does. Links between published notes work; nothing else is visible. The owner's page is also at plain /public.

Search engines are kept out unless you turn on Let search engines find it for a note (searchable: true).

History and export

  • Version history lists earlier versions of a note to read or restore.
  • Settings → Download all notes gives you a zip of your whole folder.

Calendar feed

Settings → Calendar feed makes a private link that Google or Apple Calendar can subscribe to. Open todos with a date or reminder show up as all-day or timed events, repeats included. Add it as a calendar "from URL".

Keep the link private. Calendar apps can't sign in, so the secret is in the link. It only opens the feed, nothing else, but anyone holding it can read your dated todos until you revoke or replace it.

Web clipper

Save a web page's article as a markdown note, with its address in the note's source property. Three ways in:

  • New → Clip a web page and paste the address.
  • The bookmarklet from Settings → Clip web pages clips the page you're on. Sink asks before saving.
  • Share → Sink on Android, or the installed web app, with a link.

Sink fetches public pages only, never anything on your own network. AI assistants can clip too, with clip_url.

Importing

Google Keep

Export Keep from Google Takeout, then import the zip in Settings. Checklists, labels (as tags), colours, pins and images come across. The zip is read in your browser.

Notion

Export from Notion as Markdown & CSV, then import it in Settings. The page tree, links between pages and images come across, and databases become tables, with each row's properties in its page's frontmatter.

AI assistants (MCP)

Open Settings → AI assistants for the connector URL, https://<your Sink address>/mcp. Add it as a custom connector in Claude, ChatGPT or Poke; you sign in to Sink and approve it. For Claude Code, make a token on the same page and run the command it shows.

AreaTools
Notessearch_notes, read_note, save_note, style_note, clip_url
Folderscreate_folder, move_note
Todoslist_todos, add_todo, complete_todo, update_todo
Trashtrash_note, list_trash, restore_from_trash

An assistant works on the notes of whoever connected it. It can't delete anything for good, share or publish notes, export, or manage sign-ins. Revoke it in Settings.

Plugins

Plugins run for the owner's notes. Built in, and on unless you list them in SINK_PLUGINS_DISABLED:

idWhat it does
diagrams```mermaid blocks render as Mermaid diagrams
math```math blocks render with KaTeX
dailyA "Today's note" button made from Templates/Daily.md, and an assistant tool that adds to it. Set SINK_PLUGIN_DAILY_FOLDER and SINK_PLUGIN_DAILY_TEMPLATE to change where.
webhooksSends note and todo events to your URLs. See Webhooks.

Writing your own

A plugin is a folder in ./plugins with a plugin.json. Restart Sink to load it. The word count example is a good place to start.

{
  "id": "word-count",
  "name": "Word count",
  "version": "1.0.0",
  "description": "What it does, in a sentence.",
  "server": "server.ts",
  "client": "client.js",
  "styles": "styles.css"
}

All three parts are optional; a plugin can be just a stylesheet.

Only install plugins you trust. A plugin's server part runs inside Sink with access to all your notes, like an Obsidian plugin.

Server part

export default function setup(sink) {
  sink.routes.get("/hello", (c) => c.json({ hi: true }));  // GET /api/plugins/<id>/hello
  sink.on(async (event) => { /* react to changes */ });
  sink.mcpTool("name", { description: "…", inputSchema: {} }, async (args) => "result");
  sink.every(60 * 60 * 1000, async () => { /* hourly */ });
}
sink.vaultlist(), read(path), write(path, content, hash), create(folder, title, content), move(from, to), trash(path), saveAttachment(name, bytes). write needs the hash from read (or null for a new note) and refuses if the note changed, so a plugin never overwrites an edit.
sink.on(fn)Every change: note.created, note.updated, note.deleted, note.moved, todo.done, todo.undone. source is "external" for edits made outside Sink.
sink.routesA Hono app at /api/plugins/<id>/, already signed in.
sink.mcpTool()A tool for AI assistants, named <id>_<name>. inputSchema is a map of zod schemas.
sink.every(ms, fn)A scheduled job that never runs twice at once.
sink.env(key)Reads SINK_PLUGIN_<ID>_<KEY> from .env.
sink.log(), sink.timeZoneLogging, and the owner's time zone.

Client part

A plain JavaScript module, no build step. It runs in the web app and in the Android editor.

export default function setup(sink) {
  sink.codeBlock("chart", (source, el, { dark }) => { el.textContent = source; });
  sink.command({ id: "hello", name: "Insert a greeting", run: (ctx) => ctx.insert("Hello!") });
  sink.gridAction({ id: "random", label: "Random note", icon: "casino",
                    run: (ctx) => ctx.openNote("Ideas.md") });
}
sink.codeBlock()Renders ```lang blocks; shown as text while you edit them.
sink.command()A slash command, with an optional Material Symbols icon. ctx has insert(text), text() and the CodeMirror view.
sink.gridAction()A button by "Take a note…" on the web. icon is a Material Symbols name.
sink.api(path)fetch for your plugin's own routes, signed in.

Style with the page's colour variables, like --md-sys-color-primary, to match light and dark. The full reference is in docs/plugins.md.

Webhooks

Set SINK_PLUGIN_WEBHOOKS_URLS and Sink POSTs each event as JSON to n8n, Home Assistant, Zapier or your own script:

{ "event": "todo.done", "path": "Groceries.md", "text": "Oat milk",
  "source": "sink", "at": "2026-11-10T08:12:00.000Z" }
  • SINK_PLUGIN_WEBHOOKS_EVENTS limits which events are sent (default all).
  • While you type, note.updated waits until the note has been quiet for 5 seconds, so a burst of autosaves sends one event. Failed deliveries are retried three times.
  • With SINK_PLUGIN_WEBHOOKS_SECRET set, X-Sink-Signature is sha256= plus the HMAC-SHA256 of the raw body. Check it:
const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-sink-signature"] ?? ""))) reject();

Email in

Optional, and for the owner's notes. Give Sink a mailbox (a dedicated address with plus-addressing works best) by filling in the SINK_IMAP_* settings. Forward something to it and it becomes a note in Inbox/, attachments included. Send to you+todo@… and the subject becomes a todo.

SINK_IMAP_HOST, _PORT, _SECURE, _USER, _PASSWORDThe mailbox. Leave the host empty to turn email in off.
SINK_IMAP_ALLOWED_FROMAddresses or @domains allowed to send notes.
SINK_IMAP_AUTHSERV_IDRequired. Your mail provider's name in the Authentication-Results header (like mx.google.com), so only its DKIM/SPF verdict is trusted.
SINK_IMAP_MAILBOX, _PROCESSED_FOLDER, _REJECTED_FOLDERWhere to read from, and where handled and refused mail is moved.

Backups

Back up ./notes (the owner's notes) and ./data, which also holds everyone else's notes in data/users unless you moved them. Sink keeps daily database snapshots in data/backups. The search index rebuilds itself from the notes, so if you lose the database you lose nothing a rescan can't bring back.

Notes deleted in Sink stay in .trash/ for 30 days. Anything Obsidian or you put in .trash/ shows on the Trash page but is never removed automatically.

Security

  • Run it behind HTTPS and list every address you use in SINK_PUBLIC_URLS; browser requests from other sites are refused.
  • Sink refuses to start without someone in the allowlist, a public URL, or (with email in) SINK_IMAP_AUTHSERV_ID.
  • Assistant tokens read and write notes and todos, but can't see or create other sign-ins, share, export or empty the trash.
  • Sink won't follow symlinks out of the notes folder, so a link synced into it can't expose the server's files.
  • Each account's notes live in their own folder and database; nothing one account does can reach another's.
  • Share links and public pages show only that note's text and the images it embeds.
  • The calendar feed token only opens the feed. The clipper only fetches public addresses.

Development

The server is Bun, Hono and SQLite; the web app is Vite with Material 3 web components and CodeMirror; the Android app is Kotlin and Jetpack Compose; the Obsidian plugin is TypeScript.

cd server && bun install && bun test       # API
cd web && bun install && bun run dev        # web app, proxies /api to :8787
cd android && ./gradlew assembleDebug       # run `bun run build` in web/ first
cd obsidian && bun install && bun test   # Obsidian plugin, tested against ../server

Issues and pull requests are welcome on GitHub.