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
| Folder | What's in it |
|---|---|
./notes | Your notes, one .md file each. Point it at an existing folder or Obsidian vault by changing the ./notes:/notes line in docker-compose.yml. |
./data | The database: search index, sign-ins, settings, daily snapshots. Keep it on local disk; SQLite on a network share can corrupt. |
./plugins | Plugins 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 inSINK_PUBLIC_URLS - Scopes:
openid email profile - Client type: confidential (with a secret), or public (PKCE only; leave
SINK_OIDC_CLIENT_SECRETempty)
| Provider | Issuer URL looks like |
|---|---|
| Pocket ID | https://id.example.com (simplest to self-host: passkeys only) |
| authentik | https://auth.example.com/application/o/<app slug>/ |
| Authelia | https://auth.example.com |
| Keycloak | https://kc.example.com/realms/<realm> |
https://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(oremail:you@example.com): your email, if the provider says it's verifieduser:you: your username at the provider. Only use this if people can't pick their own usernames theresub: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.
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(defaultdata/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.
Settings
Everything goes in .env. Restart with docker compose up -d after changing it.
| Setting | What it does |
|---|---|
SINK_PUBLIC_URLS | Every 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_ISSUER | The provider's base URL (the one serving /.well-known/openid-configuration). |
SINK_OIDC_CLIENT_IDSINK_OIDC_CLIENT_SECRET | The client you made. Leave the secret empty for a public client. |
SINK_OIDC_ALLOWED_USERSSINK_OIDC_ALLOWED_GROUPS | Who may sign in, comma-separated. More people can be added in Settings → People. See Sign-in. |
SINK_OIDC_NAME | Shown on the button: "Sign in with Pocket ID". |
SINK_TIMEZONE | Your time zone, for reminders and note dates. Pacific/Auckland, Europe/London… |
SINK_USERS_DIR | Where everyone but the owner keeps their notes and database. Default data/users. |
SINK_NOTES_SCAN_SECONDS | How often to rescan the notes folder for edits made outside Sink. Default 30. |
PUID / PGID | User and group Sink runs as. Default 1000. |
SINK_TRASH_DAYS | Days deleted notes stay in .trash/. Default 30; 0 keeps them forever. |
SINK_BACKUP_KEEP | Days of database snapshots kept in data/backups. Default 7; 0 turns them off. |
SINK_MAX_UPLOAD_MB | Largest attachment you can upload. |
SINK_PLUGINS_DISABLED | Built-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.



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.
| Type | Get |
|---|---|
- [ ] 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 |
```js | A code block, coloured by language |
#tag | A tag; search #tag to filter |
> [!tip] Title | A callout |
/table | A table you can edit in place |
/template | The contents of a note from your Templates/ folder |
/mermaid, /math | A diagram or formula (built-in plugins) |
/today, /date, /time | Today'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 / ⌘ K | Jump to any note |
| N | New note |
| / | Search notes |
| Ctrl S / ⌘ S | Save now |
| Esc | Close 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.




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
| Mark | Means |
|---|---|
📅 date | Due. Reminds at 9am that day unless it has a time. |
(@date 10:00) | Remind at this time (Obsidian Reminder plugin format). |
⏳ date | Scheduled: when you plan to do it. Stands in for a due date. |
🛫 date | Starts: hidden from the list until then. |
🔁 every week | Repeats. Ticking it adds the next one with the dates moved on. |
🔺 ⏫ 🔼 🔽 ⏬ | Priority, highest to lowest. Sorted and shown in the list. |
✅ date, ❌ date | Done 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.
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.
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".
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.
| Area | Tools |
|---|---|
| Notes | search_notes, read_note, save_note, style_note, clip_url |
| Folders | create_folder, move_note |
| Todos | list_todos, add_todo, complete_todo, update_todo |
| Trash | trash_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:
| id | What it does |
|---|---|
diagrams | ```mermaid blocks render as Mermaid diagrams |
math | ```math blocks render with KaTeX |
daily | A "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. |
webhooks | Sends 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.
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.vault | list(), 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.routes | A 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.timeZone | Logging, 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_EVENTSlimits which events are sent (default all).- While you type,
note.updatedwaits 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_SECRETset,X-Sink-Signatureissha256=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, _PASSWORD | The mailbox. Leave the host empty to turn email in off. |
SINK_IMAP_ALLOWED_FROM | Addresses or @domains allowed to send notes. |
SINK_IMAP_AUTHSERV_ID | Required. 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_FOLDER | Where 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.