Quick Start • Features • Configuration • Usage
Optional login • Demo data • Development • Contributing
MIT License — free as in freedom
A self-hosted, minimal personal boards app for links and notes. Boards hold columns, columns hold cards, and each card holds an ordered mix of links, markdown notes, todo checklists, and images. One small Go binary, no framework JavaScript, your data in a single SQLite file.
Dark → light: notes, links, new cards, drag & drop, collapsing columns. Click for the video.
- Boards, columns, cards — switch boards from the navbar; collapse columns into slim rails when you need focus.
- Four block types per card —
linklists with auto-fetched site icons and page titles,noteblocks with markdown (#/##/###headers,-/*and1./1)lists,---/===/***rules,**bold**,*italic*,`code`),todochecklists (one block = one list, Enter adds the next item), andimageblocks via upload or URL. - Drag and drop — cards within and across columns, blocks via their handle, columns by their header; drop a card onto the navbar board strip to copy or move it to another board.
- Inline everything — click any text to edit, blur commits; compact
+ card/+ link/+ note/+ imageadders everywhere. - Board backgrounds + column colors — six paper-like board themes, per-column color washes that persist.
- Import / export — legacy v1 JSON importer (additive-only, link dedupe on normalized URL) plus a full v2 export for backups.
- Optional login — OpenID Connect, off by default. Turn it on from Settings and boards go private with per-board viewer/editor invites.
- Fast + offline-friendly — cache-first instant paint, service-worker app shell, lazy images.
- Lightweight — single Go binary, stdlib
net/http, SQLite. - Minimal footprint — one Docker image, DB in a
/datavolume. - Small client — initial JS ≤50KB gzipped (currently 41.0KB;
re-check with
sh scripts/budget-check.sh). - Instant load — cache/seed → first paint target <100ms
(instrumented as
window.__LOOM_FIRST_PAINT_MS; measure in a live tab, never trust a quoted number).
🐳 Docker (recommended)
docker build -t loom .
docker run -p 8080:8080 -v loom-data:/data loomOr with Docker Compose — compose.yaml builds locally, while
compose.ghcr.yaml uses the prebuilt image (same loom-data
volume on port 8080 either way):
# Local build:
docker compose up --build -d
# Prebuilt GHCR image, no build:
docker compose -f compose.ghcr.yaml up -d
docker compose downOpen http://localhost:8080. Your database lives
in the loom-data volume (/data/loom.db inside the container).
Prebuilt images publish when a release is pushed to GitHub:
ghcr.io/crueber/loom:latest (plus sha-<short-SHA> and vX.Y.Z tags).
🏃 Go run (local dev)
# SQLite (same backend Docker uses):
go run ./cmd/loom --addr :8080 --data loom.db --web web
# JSON-file backend (zero dependencies, handy for hacking):
go run ./cmd/loom --addr :8080 --data loom-data.json --web web
# In-memory (no persistence, throwaway tests):
go run ./cmd/loom --addr :8080 --data "" --web webOn first run with an empty store, Loom seeds a Home board with a
Start here column and a welcome card, so a new tab is never empty.
No config files, no environment variables. Everything optional lives in the Settings dialog in the UI (theme, language, OIDC provider, login requirements).
| Flag | Default | Meaning |
|---|---|---|
--addr |
:8080 |
listen address |
--data |
loom-data.json |
storage: .db/.sqlite/.sqlite3 → SQLite, any other path → JSON file, empty → in-memory |
--web |
web |
web assets directory |
Image uploads (jpeg/png/gif, ≤12MB) need the SQLite backend; the
JSON-file backend answers 501 for uploads.
Loom is open single-user software out of the box — no account, no password. If you want private boards and sharing:
- Open Settings → Account and enter your OIDC issuer, client ID, and secret (any OpenID Connect provider works).
- Flip on login. New boards become private automatically; existing boards stay public until you change them.
- Use the per-board Share dialog to invite viewers/editors.
Sessions live in an HttpOnly SameSite cookie; theme + language prefs sync across your devices when signed in.
Recommended for home labs: run Passage as your default OIDC provider. It is a self-hosted single sign-on service built for exactly this setup — passkeys, magic links, upstream identity providers, and per-app access policies — so Loom and every other service on your network share one login.
📝 Boards, columns, cards
+ board/+ columnin the navbar append to the end.- Click a column header to collapse it to a rail; click empty rail space
to expand. The header
▾menu holds color swatches, Rename, Delete. + cardsits at the bottom of every column; each card offers+ link/+ note/+ image(andTodo…for checklists).- The card toolbar appears on hover/focus; deleting asks via a confirm dialog (Esc cancels, nothing is deleted).
- Rename the board or delete it from Settings → General.
🎯 Organizing
- Drag cards within or across columns; drag blocks by their slim handle to reorder within or across cards; drag columns by the header.
- Drag a card onto the navbar board strip to copy/move it to another board (uses the existing create + delete APIs).
- Drag a column's header handle to resize it (widths persist locally); double-click the handle resets to standard width.
- Todo blocks: Enter adds the next item ready to type, Escape exits, checkbox toggles save.
💾 Import / export
- Settings → Data imports a v1 legacy JSON export as a new board tree (never modifies existing data; links dedupe on normalized URL).
GET /api/exportreturns a full v2 backup (all boards + trees).
The demo video above comes from a small demo board. Rebuild it on any fresh server (SQLite backend, since two cards use uploaded images):
go run ./cmd/loom --addr 127.0.0.1:8080 --data /tmp/demo.db --web web &
python3 scripts/seed-demo.py --base http://127.0.0.1:8080The script uses the auto-seeded Home board, refuses to run when that
board already holds content, and needs only the Python standard library
(images live in scripts/seed-demo-assets/).
gofmt -l . && go vet ./... && go build ./... && go test ./... && sh scripts/budget-check.shRun the full line before pushing. Conventions (branches, Forgejo PRs,
one worktree per feature, JS budget, claim verification) live in
AGENTS.md; the terse per-feature list is
FEATURES.md — every feature change updates it in the
same commit.
Suggestions and bug reports are welcome via Forgejo issues. If you want a new feature, file the request first and work through the details before sending a PR — unsolicited PRs will most likely just be closed.
Guiderails for submissions:
- No new dependencies unless strictly necessary.
- No backward-incompatible changes without migrations.
- Provide a screenshot of UI changes in the PR.
Single binary, vanilla JS, SQLite — your links, notes, and weekends.