Skip to content
Browse documentation

Screenshots (canvas previews)

canvas-drop can capture a preview screenshot of each published canvas and reuse it as the gallery cover and — for public canvases — the link-unfurl (Open Graph) image. It's an optional, off-by-default extra: when it's off, the product behaves exactly as it always has (gallery shows generative-art covers, links unfurl with the branded /og.png).

On this page

Where previews appear today: the gallery cover and the public-link OG image. The capture itself is stored once per canvas as a private, access-gated asset, so the same image can back additional surfaces (e.g. dashboard thumbnails) without re-capturing — those are wired in as the product decides to surface them.

How it works

  • Captured on publish. Publishing a canvas (editor publish or any deploy) schedules a capture. Capture is asynchronous — it never slows down or blocks a publish.
  • One preview per canvas. A canvas has exactly one current preview, stored as WebP renditions (og, card, thumb). On the default auto preview mode it is overwritten on each republish, so the image always reflects the latest published version. The owner can override this per canvas (see Per-canvas control below).
  • One browser, a small queue. A single headless Chromium runs in the server process and is reused across captures (a fresh, isolated browser context per job, recycled periodically). Jobs are drained from a small database queue one at a time by default (CANVAS_DROP_SCREENSHOTS_CONCURRENCY), so a burst of publishes just queues up.
  • Access-gated by default. Previews are stored privately and served through an access-gated route: a canvas's preview is only served to someone already allowed to see that canvas. Restricted and otherwise gated canvas previews are never exposed publicly — a per-canvas OG image is emitted only for public_link canvases.
  • Capture is sandboxed. While a canvas is being captured, its backend primitives (AI, realtime, network) are neutered — a capture makes no AI spend and no outbound network calls. Dialogs are dismissed and a hard timeout bounds a slow/looping canvas. The capture browser itself can only reach this instance: it runs behind a proxy that cannot be reached, with only the instance's own loopback address (and, in subdomain mode, *.{baseHost}, mapped to loopback) exempted. WebRTC may not send UDP around the proxy, and service workers are blocked. So a canvas's WebSocket, popup or worker can't reach an internal service or the internet either.

Enablement — two org-wide layers

Auto-capture only runs when both org-wide layers say yes (each canvas owner can then further opt out or override per canvas — see Per-canvas control below):

  1. Environment availability — CANVAS_DROP_SCREENSHOTS must be on, and the runtime image must actually contain Chromium (see below). This is the operator's "is this capability available at all" switch. Default: off.
  2. Admin runtime toggle — even when available, an admin must turn it on in the dashboard (Admin → Configuration → Screenshots enabled). Default: off.

When either layer is off, no browser is launched and auto previews are not served — the gallery and link unfurls behave exactly as they do today. (An owner-uploaded custom cover is independent of this gate: it's served even when auto-capture is off.)

Per-canvas control

Each canvas owner controls its cover from Settings → Preview (and over MCP via update_canvas previewMode / set_canvas_preview):

  • Automatic (auto, the default) — screenshot on publish, as described above; subject to the two org-wide layers.
  • Off (off) — never screenshot this canvas; it shows the generative cover.
  • Custom (custom) — the owner uploads a cover image. It's encoded into the same og/card/thumb renditions, pinned so a publish never overwrites it, and served even when the org-wide auto-capture pipeline is off. Removing it reverts to auto.

A link to a canvas that isn't an open public link unfurls (Slack, iMessage, …) with a generic canvas-drop sign-in card: the unfurler fetches the link signed out, so by default nothing about the canvas leaves the instance. The card is titled with the canvas name from the link itself (seenthisroadmap, for example), which the sharer already pasted; it is read from the URL, never looked up, so an unknown name gets the same card. Its image is the instance's own /og.png on the base URL.

The owner or an editor can turn a canvas's preview on or off with Settings → Cover image → Show in link previews (MCP: update_canvas linkPreview: true or false; null follows the instance default again). An admin can also set an instance default for whole-org canvases under Admin → Configuration → Access → Link previews for whole-org canvases (access.linkPreviewDefault): off (the default), title (title and description, branded image) or cover (also the custom cover). It applies to whole-org canvases that have no choice of their own; restricted canvases and password-protected public links show a preview only when turned on per canvas. Anyone holding the link can see what the default allows, in any app, not just your own workspace's chat.

A live, published, unexpired canvas whose preview is on unfurls with its title, description and custom cover. An automatic screenshot is never shown, because it can capture real content: without a custom cover the card uses the branded image. If the screenshot looks right, the owner or an editor can press Settings → Cover image → Use as custom cover (MCP: set_canvas_preview keepScreenshot: true). That keeps the current screenshot as the custom cover, exactly as if it had been uploaded: publishes stop replacing it and link previews may show it. Remove custom image (or switching automatic previews back on) returns the canvas to automatic and captures a fresh screenshot of the live version right away; the cover shows the generated placeholder until that capture finishes. The canvas itself stays behind sign-in, and turning the setting on or off is audited as a share_change. This applies in oidc auth mode, where signed-out unfurls are answered at all.

Turning it on

1. Build an image that includes Chromium

The default image does not include Chromium (it would add ~300 MB, and the feature ships disabled). Build with the opt-in build arg:

docker build --build-arg SCREENSHOTS=1 -t canvas-drop:screenshots .

This installs Chromium and its system libraries into the image. The default build (SCREENSHOTS=0) skips this entirely and stays lean.

2. Make it available in the environment

Set the env flag on the running container/instance:

CANVAS_DROP_SCREENSHOTS=on

Optional tuning (all have sensible defaults):

Variable Default What it does
CANVAS_DROP_SCREENSHOTS_CONCURRENCY 1 Captures processed at once (one browser, N contexts)
CANVAS_DROP_SCREENSHOTS_TIMEOUT_MS 20000 Hard per-capture wall-clock timeout
CANVAS_DROP_SCREENSHOTS_RECYCLE_EVERY 50 Relaunch the browser after this many jobs
CANVAS_DROP_SCREENSHOTS_LEASE_MS 120000 Job lease (a crashed worker's job is reclaimed after this)
CANVAS_DROP_SCREENSHOTS_MAX_ATTEMPTS 3 Retries before a capture is marked failed
CANVAS_DROP_SCREENSHOTS_FAILED_TTL_MS 86400000 Failed-job rows reclaimed after this
CANVAS_DROP_SCREENSHOTS_TOKEN_TTL_MS 60000 Lifetime of the internal capture credential

3. Flip the admin toggle

Sign in as an admin → Admin → Configuration → turn Screenshots enabled on. New publishes start getting previews immediately; existing canvases get one on their next publish.

Turning it off

Flip the admin toggle off (or unset CANVAS_DROP_SCREENSHOTS). Capture stops and previews are no longer served — covers revert to generative art and unfurls to the branded card. Stored previews are harmless and are reclaimed when a canvas is deleted.

Memory note

Chromium is memory-heavy. On a small single-VPS deployment, keep concurrency at 1 (the default) and rely on the per-job timeout and periodic browser recycle to bound memory. Scale concurrency up only if the host has headroom.