Excaliself

[图片]

Excaliself

Your team's whiteboard, on your server.
The Excalidraw canvas in a small self-hosted app: live collaboration, a shared team space, folders, and search, with every drawing stored in your own Postgres.

Website · Docs · 简体中文 · X

[Excaliself home screen in the light theme: a sidebar with starred drawings and folders next to a grid of drawing previews] [The same home screen in the dark theme]

[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]

Try it in 10 seconds

docker run --rm -p 127.0.0.1:3000:3000 -e PREVIEW_MODE=true ghcr.io/maciekzygmunt/excaliself

Open http://localhost:3000/preview/login to sign in as the admin, with example drawings. To test live collaboration, open http://localhost:3000/preview/login?account=new in a second browser: it signs in as a new member.

Data lives in memory and is gone when the container stops. For real use, see Deploy.

Features

• The full Excalidraw editor, with auto-save. Images pasted into a drawing are stored too.
• 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.
• Team space. A shared space every member can see and edit, next to each member's private space. Team drawings are always live.
• 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 install into it.
• Folders, stars, and recents. Nest folders and drag drawings between them in the sidebar.
• Search by title and by the text inside drawings, in the gallery and the command palette (⌘K / Ctrl K), which also runs actions.
• Import from Excalidraw+ (beta). Bring your scenes, collections, and images over with an Excalidraw+ API key (Settings → Import).
• Drop files in. Drag .excalidraw files (or .png/.svg exports with the scene) from your computer onto a folder in the sidebar.
• Trash with restore. Deleted items are purged automatically after 30 days.
• Invite-only accounts. The first visitor creates the admin account; everyone else joins by invite link.
• Connect your AI client. Claude.ai, Claude Code, Claude Desktop, and other MCP clients can find, read, and create 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.
• 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.
• Admin tools under Settings: manage members and roles, create password-reset links, and see instance stats.
• Light and dark themes, with an optional separate theme for the canvas.

Deploy

Both paths run the app and its Postgres database together from one compose file. They pull the prebuilt image ghcr.io/maciekzygmunt/excaliself (amd64 and arm64), so nothing is built on your server. latest is the newest release. The app applies database migrations when it starts, so updating is a redeploy.

Docker Compose

mkdir excaliself && cd excaliselfcurl -fsSLO https://raw.githubusercontent.com/maciekzygmunt/excaliself/main/docker-compose.yamlcurl -fsSL -o .env https://raw.githubusercontent.com/maciekzygmunt/excaliself/main/.env.example# set POSTGRES_PASSWORD, BETTER_AUTH_SECRET, and BASE_URL in .envdocker compose up -d

Open BASE_URL (default http://localhost:3000). The first visit takes you to /setup to create the admin account. Postgres is not published on the host. Put a reverse proxy with HTTPS in front of port 3000 for anything public.

To update, run docker compose pull && docker compose up -d. To pin a release, set EXCALISELF_VERSION (e.g. 1.0.0) in .env. To build the image from source instead (needs about 4 GB of RAM), clone the repo and run docker compose -f docker-compose.yaml -f docker-compose.build.yaml up -d --build. The docs have the details.

Coolify

1. Add a new resource from the public repository https://github.com/maciekzygmunt/excaliself, branch main.
2. Choose the Docker Compose build pack and set Docker Compose Location to /docker-compose.coolify.yaml.
3. Click Deploy.

Coolify creates the database, generates the secrets, and assigns a domain, so there is nothing to configure. If your server has no wildcard domain, first set a domain on the excaliself service with the container port, e.g. https://draw.example.com:3000. Open the domain to create the admin account. To pin a release instead of latest, set EXCALISELF_VERSION (e.g. 1.0.0) in the resource's environment variables. Drawings live in the pgdata volume and survive redeploys.

Configuration

Docker Compose reads these from .env. Coolify sets them for you.

GET /api/health returns 200 when the app is up and can reach Postgres.

If the only admin loses their password, see Recover admin access.

Connect an AI client (MCP)

Excaliself has an MCP server at /api/mcp. Your AI client brings the model, so the instance needs no LLM API key.

Claude.ai (web, desktop, and mobile) signs in with OAuth, with no token. In Claude, open Settings, then Connectors, click Add custom connector, and enter https://<your instance>/api/mcp. Then sign in to Excaliself and click Allow. The instance must be reachable from the public internet over HTTPS.

Other clients use an access token:

1. In Excaliself, open Settings, then MCP, and click New token. Copy the token: you see it only once.
2. Add the server to your client, with your instance's URL and the token.

Claude Code (the token dialog shows this command filled in):

claude mcp add --transport http excaliself https://draw.example.com/api/mcp \  --header "Authorization: Bearer exs_..."

Claude Desktop cannot send a token to a remote server itself, so it connects through mcp-remote, which needs Node. Open Settings, then Developer, then Edit Config, add this to claude_desktop_config.json, and restart Claude Desktop:

{  "mcpServers": {    "excaliself": {      "command": "npx",      "args": [        "-y",        "mcp-remote",        "https://draw.example.com/api/mcp",        "--header",        "Authorization:${AUTH_HEADER}"      ],      "env": { "AUTH_HEADER": "Bearer exs_..." }    }  }}

Other clients that use Streamable HTTP: the URL is https://<your instance>/api/mcp. A client that supports OAuth with dynamic client registration signs in by itself. Otherwise, send the header Authorization: Bearer <token>.

The tools:

• list_drawings, search_drawings, and list_folders find drawings, with their space and folder.
• read_drawing describes a drawing: its shapes, text, and what the arrows connect. It does not send the raw Excalidraw JSON.
• create_drawing makes a new drawing in your private space or in Team, optionally in a folder, from simple shapes and arrows or a Mermaid flowchart.
• edit_drawing proposes a change to a drawing: shapes, text, and arrows to add, change, or remove. Nothing changes until you click Apply on the drawing. get_drawing_edit tells the client whether you applied it.
• create_folder makes a folder in your private space or in Team, optionally inside another folder.
• move_drawing moves a drawing into a folder, or to the top of its space. A drawing cannot move between your private space and Team.
• trash_drawing and trash_folder move a drawing, or a folder with everything in it, to the trash. restore_drawing and restore_folder take them out again.

A token or a connected app acts as you: it sees what you see, and it can trash what you can trash. It can create drawings and folders, and move drawings between folders. It cannot change what is in a drawing until you click Apply, and it cannot delete anything for good: trashed items stay in Trash for 30 days. Revoke a token or disconnect an app under Settings at any time. When an admin deletes a member, that member's tokens and apps stop working.

Stack

TanStack Start · React 19 · Better Auth · Postgres + Drizzle · Tailwind CSS 4 + shadcn/ui on Base UI · @excalidraw/excalidraw

Local development

Requires Node 22, pnpm, and Docker.

pnpm installcp .env.dev.example .env                           # works as-isdocker compose -f docker-compose.dev.yaml up -d    # Postgres on 127.0.0.1:5432pnpm dev                                           # http://localhost:3000

pnpm dev:preview needs no Postgres and no .env: it runs in preview mode (see PREVIEW_MODE above). Open /preview/login.

pnpm test, pnpm typecheck, and pnpm lint run the checks. pnpm db:generate creates a migration after a schema change. Releases are cut from git tags; see docs/releasing.md.

Sponsors

Excaliself is free and MIT. If your team uses it, sponsoring pays for the time that goes into fixes and releases.

License

MIT. There is no promise of support or reviews for contributions, so feel free to fork it and make it yours.

Built on Excalidraw, MIT © Excalidraw. Excaliself is not affiliated with Excalidraw. "Excalidraw" is a trademark of its owner; this project uses the open-source @excalidraw/excalidraw package.