Skip to content
Back to search

excaliself

Your team's whiteboard, on your server. Self-hosted Excalidraw with accounts, folders, and search.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/maciekzygmunt/excaliself with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/maciekzygmunt/excaliself'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/maciekzygmunt--excaliself/badge.svg)](/listings/maciekzygmunt--excaliself)

HTML

<a href="/listings/maciekzygmunt--excaliself"><img src="/api/listings/maciekzygmunt--excaliself/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="public/favicon.svg" width="72" height="72" alt="">
  3. </p>
  4. <h1 align="center">Excaliself</h1>
  5. <p align="center">
  6. Your team's whiteboard, on your server.<br>
  7. The <a href="https://excalidraw.com">Excalidraw</a> canvas in a small self-hosted app: live collaboration,
  8. a shared team space, folders, and search, with every drawing stored in your own Postgres.
  9. </p>
  10. <p align="center">
  11. <a href="https://excaliself.com"><b>Website</b></a> ·
  12. <a href="https://excaliself.com/docs/"><b>Docs</b></a> ·
  13. <a href="README.zh-CN.md"><b>简体中文</b></a> ·
  14. <a href="https://x.com/0xzygmunt"><b>X</b></a>
  15. </p>
  16. <p align="center">
  17. <a href="https://www.opensourcealternatives.to"><img src="https://www.opensourcealternatives.to/badge-osa.svg" height="20" alt="As seen on Open Source Alternatives"></a>
  18. </p>
  19. <p align="center">
  20. <img src="docs/images/home-light.png" width="49%" alt="Excaliself home screen in the light theme: a sidebar with starred drawings and folders next to a grid of drawing previews">
  21. <img src="docs/images/home-dark.png" width="49%" alt="The same home screen in the dark theme">
  22. </p>
  23. <p align="center">
  24. <img src="docs/images/live-collab.gif" width="100%" alt="Two browsers edit one drawing: a box drawn on the left appears live on the right, an arrow drawn on the right appears on the left, and after a reload every change is still there">
  25. </p>
  26. ## Try it in 10 seconds
  27. ```bash
  28. docker run --rm -p 127.0.0.1:3000:3000 -e PREVIEW_MODE=true ghcr.io/maciekzygmunt/excaliself
  29. ```
  30. Open <http://localhost:3000/preview/login> to sign in as the admin, with example
  31. drawings. To test live collaboration, open
  32. <http://localhost:3000/preview/login?account=new> in a second browser: it signs
  33. in as a new member.
  34. Data lives in memory and is gone when the container stops. For real use, see
  35. [Deploy](#deploy).
  36. ## Features
  37. - **The full Excalidraw editor**, with auto-save. Images pasted into a drawing are stored too.
  38. - **Live collaboration.** Share a drawing by link and edit it together in real time, with live cursors and follow mode. Links can be for members only or for anyone, including guests without an account.
  39. - **Team space.** A shared space every member can see and edit, next to each member's private space. Team drawings are always live.
  40. - **Team library.** One Library panel of shapes and icons for the whole team, saved on the server and updated live. Libraries from [libraries.excalidraw.com](https://libraries.excalidraw.com) install into it.
  41. - **Folders, stars, and recents.** Nest folders and drag drawings between them in the sidebar.
  42. - **Search** by title and by the text inside drawings, in the gallery and the command palette (<kbd>⌘K</kbd> / <kbd>Ctrl K</kbd>), which also runs actions.
  43. - **Import from Excalidraw+ (beta).** Bring your scenes, collections, and images over with an Excalidraw+ API key (Settings → Import).
  44. - **Drop files in.** Drag `.excalidraw` files (or `.png`/`.svg` exports with the scene) from your computer onto a folder in the sidebar.
  45. - **Trash** with restore. Deleted items are purged automatically after 30 days.
  46. - **Invite-only accounts.** The first visitor creates the admin account; everyone else joins by invite link.
  47. - **Connect your AI client.** Claude.ai, Claude Code, Claude Desktop, and other MCP clients can find, read, create, and export drawings, propose changes to them, and move them to the trash. A change waits on the canvas until you click Apply, and then everyone in the drawing sees it live. Clients sign in with OAuth or a personal access token. The instance needs no LLM API key.
  48. - **Single sign-on** with Google Workspace, Microsoft Entra ID, or any OIDC provider (Okta, Authentik, Keycloak). People from your email domains join on their first sign-in, with no invite.
  49. - **Admin tools** under Settings: manage members and roles, create password-reset links, and see instance stats.
  50. - **Light and dark themes**, or follow the system setting, with an optional separate theme for the canvas.
  51. ## Deploy
  52. Each path runs the app next to its Postgres database and pulls the prebuilt
  53. image `ghcr.io/maciekzygmunt/excaliself` (amd64 and arm64), so nothing is built
  54. on your server. The same image is on Docker Hub as
  55. [`maciekzygmunt/excaliself`](https://hub.docker.com/r/maciekzygmunt/excaliself).
  56. `latest` is the newest release. The app applies database
  57. migrations when it starts, so updating is running a newer image.
  58. ### Docker Compose
  59. ```bash
  60. mkdir excaliself && cd excaliself
  61. curl -fsSLO https://raw.githubusercontent.com/maciekzygmunt/excaliself/main/docker-compose.yaml
  62. curl -fsSL -o .env https://raw.githubusercontent.com/maciekzygmunt/excaliself/main/.env.example
  63. # set POSTGRES_PASSWORD, BETTER_AUTH_SECRET, and BASE_URL in .env
  64. docker compose up -d
  65. ```
  66. Open `BASE_URL` (default <http://localhost:3000>). The first visit takes you to
  67. `/setup` to create the admin account. Postgres is not published on the host.
  68. Put a reverse proxy with HTTPS in front of port 3000 for anything public.
  69. To update, run `docker compose pull && docker compose up -d`. To pin a release,
  70. set `EXCALISELF_VERSION` (e.g. `1.0.0`) in `.env`. To build the image from
  71. source instead (needs about 4 GB of RAM), clone the repo and run
  72. `docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build`.
  73. The [docs](https://excaliself.com/docs/docker-compose/) have the details.
  74. ### Coolify
  75. 1. Add a new resource from the public repository
  76. `https://github.com/maciekzygmunt/excaliself`, branch `main`.
  77. 2. Choose the **Docker Compose** build pack and set **Docker Compose Location** to
  78. `/docker-compose.coolify.yaml`.
  79. 3. Click **Deploy**.
  80. Coolify creates the database, generates the secrets, and assigns a domain, so
  81. there is nothing to configure. If your server has no wildcard domain, first set a
  82. domain on the `excaliself` service with the container port, e.g.
  83. `https://draw.example.com:3000`. Open the domain to create the admin account.
  84. To pin a release instead of `latest`, set
  85. `EXCALISELF_VERSION` (e.g. `1.0.0`) in the resource's environment variables.
  86. Drawings live in the `pgdata` volume and survive redeploys.
  87. ### Railway
  88. [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/excaliself)
  89. The template runs the app next to a Railway Postgres database. It generates the
  90. auth secret and a domain, so there is nothing to configure. Open the domain to create
  91. the admin account. To set it up by hand or to upgrade, see the
  92. [docs](https://excaliself.com/docs/railway/).
  93. ### Hostinger
  94. [![Deploy on Hostinger](https://assets.hostinger.com/vps/deploy.svg)](https://www.hostinger.com/docker-hosting?compose_url=https://raw.githubusercontent.com/maciekzygmunt/excaliself/main/docker-compose.yaml)
  95. The button opens Hostinger's Docker Manager with `docker-compose.yaml`. Before
  96. you deploy, set `POSTGRES_PASSWORD`, `BETTER_AUTH_SECRET`, and `BASE_URL` in the
  97. project's environment, as for [Docker Compose](#docker-compose). Open `BASE_URL`
  98. to create the admin account. See the [docs](https://excaliself.com/docs/hostinger/).
  99. ### App stores
  100. - **TrueNAS**: in **Apps**, search for Excaliself (community train). Set
  101. **App URL** to the address you open it at.
  102. [Store page](https://apps.truenas.com/catalog/excaliself_community/).
  103. - **Unraid**: in **Apps**, search for Excaliself. Install **postgresql17**
  104. first. [Store page](https://ca.unraid.net/apps/excaliself-1ulvvg01m0exfg).
  105. - **Portainer**: in the
  106. [Portainer Templates](https://portainer-templates.as93.net/excaliself) list.
  107. The [docs](https://excaliself.com/docs/app-stores/) have the fields to fill in.
  108. ### Configuration
  109. Docker Compose reads these from `.env`. Coolify sets them for you.
  110. | Variable | Required | Description |
  111. |---|---|---|
  112. | `POSTGRES_PASSWORD` | Yes | Password for the bundled Postgres. Use hex (`openssl rand -hex 24`): it goes into a connection URL |
  113. | `BETTER_AUTH_SECRET` | Yes | Session signing secret, at least 32 characters (`openssl rand -base64 32`) |
  114. | `BASE_URL` | Yes in production | Public URL of the instance (default `http://localhost:3000`) |
  115. | `EXCALISELF_VERSION` | No | Image tag to run: `latest` (default), a release like `1.0.0` or `1.0`, or `main` |
  116. | `EXCALISELF_PORT` | No | Host port for the app (default `3000`). `127.0.0.1:3000` keeps it local to a reverse proxy |
  117. | `POSTGRES_USER`, `POSTGRES_DB` | No | Bundled Postgres user and database (default `excaliself`) |
  118. | `IMAGE_UPLOADS_PER_MINUTE` | No | Image uploads allowed per minute, per IP, in each live drawing (default `30`). See [Environment variables](https://excaliself.com/docs/environment/#limits) |
  119. | `GOOGLE_*`, `MICROSOFT_*`, `OIDC_*`, `SSO_ALLOWED_DOMAINS` | No | Single sign-on. See [Single sign-on](https://excaliself.com/docs/single-sign-on/) |
  120. | `PREVIEW_MODE` | No | `true` runs a throwaway instance for a pull request preview: an in-memory PGlite instead of Postgres, seeded with an admin and example drawings. It ignores `DATABASE_URL` and `BASE_URL` and makes `BETTER_AUTH_SECRET` optional. `/preview/login` signs in as the admin (`admin@example.com` / `preview-password`), `/preview/login?account=new` as a new member. Data is lost on restart. See [PR previews](./docs/pr-previews.md) |
  121. | `PREVIEW_HOSTS` | With `PREVIEW_MODE` behind a domain | Comma-separated hosts a preview answers on, e.g. `*.draw.example.com`. Auth refuses other hosts; localhost always works |
  122. `GET /api/health` returns `200` when the app is up and can reach Postgres.
  123. If the only admin loses their password, see
  124. [Recover admin access](https://excaliself.com/docs/admin-recovery/).
  125. ## Connect an AI client (MCP)
  126. Excaliself has an [MCP](https://modelcontextprotocol.io) server at `/api/mcp`.
  127. Your AI client brings the model, so the instance needs no LLM API key.
  128. **Claude.ai** (web, desktop, and mobile) signs in with OAuth, with no token.
  129. In Claude, open **Settings**, then **Connectors**, click **Add custom
  130. connector**, and enter `https://<your instance>/api/mcp`. Then sign in to
  131. Excaliself and click **Allow**. The instance must be reachable from the
  132. public internet over HTTPS.
  133. Other clients use an access token:
  134. 1. In Excaliself, open **Settings**, then **MCP**, and click
  135. **New token**. Copy the token: you see it only once.
  136. 2. Add the server to your client, with your instance's URL and the token.
  137. **Claude Code** (the token dialog shows this command filled in):
  138. ```bash
  139. claude mcp add --transport http excaliself https://draw.example.com/api/mcp \
  140. --header "Authorization: Bearer exs_..."
  141. ```
  142. **Claude Desktop** cannot send a token to a remote server itself, so it
  143. connects through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote),
  144. which needs Node. Open **Settings**, then **Developer**, then **Edit Config**,
  145. add this to `claude_desktop_config.json`, and restart Claude Desktop:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "excaliself": {
  150. "command": "npx",
  151. "args": [
  152. "-y",
  153. "mcp-remote",
  154. "https://draw.example.com/api/mcp",
  155. "--header",
  156. "Authorization:${AUTH_HEADER}"
  157. ],
  158. "env": { "AUTH_HEADER": "Bearer exs_..." }
  159. }
  160. }
  161. }
  162. ```
  163. **Other clients** that use Streamable HTTP: the URL is
  164. `https://<your instance>/api/mcp`. A client that supports OAuth with dynamic
  165. client registration signs in by itself. Otherwise, send the header
  166. `Authorization: Bearer <token>`.
  167. The tools:
  168. - `list_drawings`, `search_drawings`, and `list_folders` find drawings, with
  169. their space and folder.
  170. - `read_drawing` describes a drawing: its shapes, text, and what the arrows
  171. connect. It does not send the raw Excalidraw JSON.
  172. - `export_drawing` exports a drawing as a PNG or SVG image, for example for
  173. your documentation. An SVG contains the drawing's fonts. `export_scene`
  174. exports it as an `.excalidraw` file.
  175. - `create_drawing` makes a new drawing in your private space or in Team,
  176. optionally in a folder, from simple shapes and arrows or a Mermaid flowchart.
  177. - `edit_drawing` proposes a change to a drawing: shapes, text, and arrows to
  178. add, change, or remove. Nothing changes until you click **Apply** on the
  179. drawing. `get_drawing_edit` tells the client whether you applied it.
  180. - `create_folder` makes a folder in your private space or in Team, optionally
  181. inside another folder.
  182. - `move_drawing` moves a drawing into a folder, or to the top of its space. A
  183. drawing cannot move between your private space and Team.
  184. - `trash_drawing` and `trash_folder` move a drawing, or a folder with
  185. everything in it, to the trash. `restore_drawing` and `restore_folder` take
  186. them out again.
  187. A token or a connected app acts as you: it sees what you see, and it can
  188. trash what you can trash. It can create drawings and folders, and move
  189. drawings between folders. It cannot change what is in a drawing until you
  190. click **Apply**, and it cannot delete anything for good: trashed items stay
  191. in Trash for 30 days.
  192. Revoke a token or disconnect an app under Settings at any time. When an admin
  193. deletes a member, that member's tokens and apps stop working.
  194. ## Stack
  195. [TanStack Start](https://tanstack.com/start) · React 19 ·
  196. [Better Auth](https://www.better-auth.com) · Postgres + [Drizzle](https://orm.drizzle.team) ·
  197. Tailwind CSS 4 + shadcn/ui on [Base UI](https://base-ui.com) ·
  198. [`@excalidraw/excalidraw`](https://github.com/excalidraw/excalidraw)
  199. ## Local development
  200. Requires Node 22, pnpm, and Docker.
  201. ```bash
  202. pnpm install
  203. cp .env.dev.example .env # works as-is
  204. docker compose -f docker-compose.dev.yaml up -d # Postgres on 127.0.0.1:5432
  205. pnpm dev # http://localhost:3000
  206. ```
  207. `pnpm dev:preview` needs no Postgres and no `.env`: it runs in preview mode
  208. (see `PREVIEW_MODE` above). Open `/preview/login`.
  209. `pnpm test`, `pnpm typecheck`, and `pnpm lint` run the checks.
  210. `pnpm db:generate` creates a migration after a schema change.
  211. Releases are cut from git tags; see [docs/releasing.md](./docs/releasing.md).
  212. ## Sponsors
  213. Excaliself is free and MIT. If your team uses it,
  214. [sponsoring](https://github.com/sponsors/maciekzygmunt) pays for the time that
  215. goes into fixes and releases.
  216. ## License
  217. [MIT](./LICENSE). There is no promise of support or reviews for contributions,
  218. so feel free to fork it and make it yours.
  219. Built on [Excalidraw](https://github.com/excalidraw/excalidraw), MIT © Excalidraw.
  220. Excaliself is not affiliated with Excalidraw. "Excalidraw" is a trademark of
  221. its owner; this project uses the open-source `@excalidraw/excalidraw` package.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.