Desktop app
End users should download a release from GitHub Releases and follow the Quickstart. This page explains how the app is built.
The local build and its per-seam local backends —
sandbox, Yjs host,
blob store, database, engine — are assembled into a
single desktop app by a Tauri shell that runs the Next app as a
bundled Node sidecar (#418, #404). The Tauri shell lives in
apps/desktop.
The single build switch
Every local backend is selected together in one place,
apps/desktop/desktop.env. Each seam still reads its own env var (the switches
are independent by design); this profile is where the desktop distribution sets
them as a set, so one repository produces both the hosted deployment (none set) and the
desktop app:
SCREENPLAY_DESKTOP=1 # emit `output: standalone`
NEXT_PUBLIC_SCREENPLAY_PROFILE=desktop # the desktop capabilities
NEXT_PUBLIC_YJS_HOST=local # local y-websocket host
NEXT_PUBLIC_BASE_PATH= # served at the origin root (no /app proxy)
SANDBOX_BACKEND=local # each chat’s code is a git worktree on the host
# ("worktree", the old value, still accepted)
SCREENPLAY_DB=pglite # embedded Postgres
BLOB_STORE=local-fs # thumbnails to local disk
AGENT_ENGINE=external # chat via the installed CLI's ACP adapter
THUMBNAIL_CAPTURER=tauri-webview
# SCREENPLAY_ACP_HARNESS=codex # optional: which installed CLI backs agent
# chat; unset → defaults to claude-codeThe NEXT_PUBLIC_* half is inlined at next build; the seam selectors are read
at runtime and re-injected by the Tauri shell when it spawns the sidecar.
Lifecycle
Tauri owns the sidecar end-to-end. All of this runs off the main thread, so the window paints a loading screen (the app’s spinner arc drawn in the homepage’s liquid dither, on the app’s own light or dark background) the moment the app opens:
- Port — binds
127.0.0.1:0for a free port and hands it to the sidecar. - Spawn — extracts the bundled tree (while recovering the login shell’s
PATHin parallel) and runsnode apps/app/server.jswith the desktop profile, the machine-specific data dirs (under the OS app-data directory), and the per-install secrets. - Health gate — polls
/api/healthand only navigates the webview to the local server once it 200s, so first paint never races the boot. If the sidecar exits or never answers, the loading screen says Screenplay couldn’t start instead of spinning forever. - Shutdown — kills and reaps the sidecar on quit (no orphan).
Secrets
ENCRYPTION_KEY (encrypts saved repositories, environment variable values, and account memory, files and skills lists at rest) and
TERMINAL_AUTH_SECRET are deployment secrets in the hosted app. A desktop
install has no deployment, so the Tauri shell mints and persists them on first
launch next to the app data — stable across restarts, unique per install.
Thumbnails
The desktop build ships no headless Chromium, so the
blob store’s thumbnail capture happens in a webview:
the sidecar’s TauriWebviewCapturer POSTs each render URL to the Tauri shell’s
localhost control server (TAURI_CONTROL_URL), which renders it off-screen and
returns a PNG via the platform webview’s snapshot API. The local-fs store writes
the WebP and serves it back from the sidecar’s own /blobs route.
The same control server snapshots the canvas window itself when a chat’s agent
uses a frame and checks a step.
It also plays the agent’s clicks and keys as real input to the canvas window,
sets your clipboard aside around a step that copies or pastes, and answers a
file picker the agent’s click opens with files from the code of the frame’s chat.
These act on your screen and clipboard, so the Tauri shell mints a token at launch
and hands it only to the sidecar (TAURI_CONTROL_TOKEN); a snapshot or input
request without it is refused. The agent’s steps reach the canvas over a
WebSocket on the local Yjs server’s port, behind the same per-launch secret and
Origin check as the Yjs sync connection.
Sharing
People on your tailnet can watch a canvas while you work in it. Sharing is off until you turn it on.
Turning it on and off
Click Share in a canvas’s top right and turn on Sharing. The dialog then shows the canvas’s link; Copy link copies it to send. Sharing is one switch for the whole Mac: while it’s on, anyone you sent any canvas’s link to can open it. It stays on when you quit and reopen the app, until you turn it off.
Turning it on opens the viewer listener on 127.0.0.1 and serves it to
your tailnet with tailscale serve, through the
preview exposure. It needs
Tailscale installed, signed in and connected, with MagicDNS and HTTPS
Certificates turned on for your tailnet. When something’s missing, the switch
stays off and the dialog says what.
Turning it off closes the viewer listener, ends every viewer’s connection,
and stops serving the listener and every preview a viewer opened over your
tailnet (tailscale serve … off for each port). Whether Sharing is on, its
port and the ports it served are kept in sharing.json in the app’s data
folder, so a canvas keeps its link and an exposure left over from a crash is
released on the next launch.
What viewers see
Each canvas has one link:
https://<your Mac>.<tailnet>.ts.net:<viewer port>/s/<canvas id>/<key>The key is worked out from the install’s ENCRYPTION_KEY, so nothing is
stored: a canvas’s link stays the same for as long as the install does, and
there’s no way to reset it. Anyone you sent it to can come back to it. A wrong
key, or a link for a canvas you deleted, shows nothing. There’s no home screen
for viewers either: a link opens one canvas, and nothing else.
Links work only on the viewer listener, which serves a short list of reads and refuses every write but comments (see Viewer identity). Someone who opens a link there watches the canvas live, as themselves:
- The canvas, as you change it. A viewer can’t change it: the server drops every change their copy sends.
- Frames, each their own copy of the preview, loaded from the
preview exposure’s address
for viewers. Your own frames stay on
localhost. - Presence: everyone’s cursor and who’s on each page. Your cursor’s name tag reads “Your name (Host)”, and your avatar in the Pages panel has a house badge. The server names each viewer from their viewer identity, whatever their page claims.
- Every chat on the canvas: its messages, steps and plans, live as the agent works, and the earlier turns from before they opened the link.
- Comments: a viewer can comment on a frame, a document or the canvas, reply to any thread, and edit or delete their own comments, all under their own name. They can resolve and reopen only the threads they started, and can’t send a thread to an agent. You see their comments as they post them and reply from your own canvas; your comments reach them the same way. Comments are the only thing a viewer can write.
A viewer otherwise only watches. None of these show on their page, and the viewer listener refuses the requests behind them:
- Sending a message, stopping a turn, or starting a new chat
- Approving a plan, answering a question, creating or merging a pull request
- Terminals: no terminal output reaches the viewer listener
- Editing the canvas: moving, resizing, renaming, the toolbar, and every ⋯ menu on frames, pages and chats
- Settings and Copy link
When you turn Sharing off, a viewer’s page says you stopped sharing. When your Mac sleeps or leaves the network, it says it can’t reach your Mac and keeps trying. Either way the canvas comes back on its own, as it is now, once Sharing is on and your Mac is reachable again. A link opened while Sharing is off doesn’t load at all, since nothing is listening.
Building
pnpm --filter desktop build:sidecar # next build → src-tauri/resources/sidecar.tar.gz
pnpm --filter desktop dev # run it (tauri dev)
pnpm --filter desktop build # package Screenplay.appThe sidecar ships as a tarball, not a directory: the Next-traced
node_modules keeps pnpm’s peer-dependency symlinks, which Tauri’s resource copy
drops — tar preserves them (and the bundled node exec bit). The build also
folds in the pieces standalone tracing misses (.next/static, public, the
drizzle/local migrations, and node-pty’s native prebuild). See
apps/desktop/README.md for the full rationale.
Prerequisites: the Rust + Tauri toolchain and node on PATH.
Releasing
Signed macOS builds are published as desktop-v<version>
GitHub Releases with the
.dmg attached twice: as Screenplay_<version>_aarch64.dmg, and as
Screenplay.dmg so that releases/latest/download/Screenplay.dmg always
fetches the newest build. They’re published by
pnpm --filter desktop release on a Mac (see Releasing the desktop app). There’s no
auto-update yet.