Local (single-user) build
Screenplay ships in two shapes from one codebase: the hosted, multi-tenant app and a single-user desktop build that needs no account or Screenplay servers (its agent still talks to your coding CLI’s provider) (#404). The desktop build swaps each cloud backend for a local one behind the seams the codebase already exposes — see Sandbox provider, Yjs host, Blob store — and, on top of those, excludes the entire multi-user surface.
The multi-user surface
The hosted app is multi-tenant: GitHub OAuth login, room_member sharing and
Yjs awareness/presence. None of that makes sense for a solo tool running on
your own machine, so the desktop build leaves it out:
- No login screen. The app opens straight into the work as a single seeded
local user (
apps/app/lib/local-user.ts). GitHub OAuth and its tables (session/account/verification) are excluded. - No membership or sharing.
canAccess/room_membercollapse to that one user — every canvas belongs to it — and the Share affordances are hidden. - No remote presence. With a single local Yjs peer there are no other cursors to show; the follow toolbar is hidden. (The awareness plumbing the collaborative editor needs stays — there is simply nobody else on it.)
Git operations use the host’s own credentials, so the brokered GitHub token and ADR 0002’s egress firewall trust boundary dissolve. Re-enabling multi-tenant operation on the local build is out of scope.
Build profiles
One build-time variable, NEXT_PUBLIC_SCREENPLAY_PROFILE, picks a build
profile. The profile sets four capabilities and the backend switches together,
so nobody assembles a combination by hand:
- Identity is who writes.
accountis many people signed in with GitHub.hostis one person running the server on their own machine, with no sign-in, as the seeded local user, using that machine’s own git,gh, coding CLIs and folders. - Multi-user surface is membership, chat senders and remote presence (above). Comments aren’t part of it: every profile has them, and in the desktop app the host and their viewers comment.
- Mac app is the desktop app’s window around the app: traffic lights, native dialogs, opening files in Finder, webview thumbnails, and the agent controlling frames in your own canvas.
- Viewers are people watching a canvas by link on a viewer listener (Sharing, in the desktop app only). Each request there is identified by the viewer identity before the app sees it.
headless is the profile for running the server on a machine you control.
pnpm headless builds and runs it; see Headless. It
also turns on hostTunnel: the host reaches the server over an SSH tunnel, so
the canvas sync and terminal connections share the app’s port, and the host’s
frames load through portless.
desktop and headless also imply the local backends: SANDBOX_BACKEND=local,
SCREENPLAY_DB=pglite, BLOB_STORE=local-fs, AGENT_ENGINE=external and
NEXT_PUBLIC_YJS_HOST=local. A backend switch you set yourself wins over the
profile’s. THUMBNAIL_CAPTURER=tauri-webview stays the Mac app’s to set, since
that capturer needs its window.
Unset, the profile is hosted, and the hosted app is unchanged. The older
NEXT_PUBLIC_SCREENPLAY_LOCAL=1 still picks desktop. The profile is
NEXT_PUBLIC_ so the same constants are inlined into both the server runtime
(auth/session, access checks) and the client bundle (the affordances that simply
don’t render), and so the bundler dead-code-eliminates the other profiles’
branches.
Read the capabilities through apps/app/lib/capabilities.ts (buildIdentity,
multiUserSurface, macShell, viewers, hostTunnel), never process.env
directly, so each gate says what it means.
Database tables
The excluded tables aren’t merely unused on the desktop build — they are never
created. The Drizzle schema is split into apps/app/lib/db/schema-core.ts (the
surviving tables: user, kv_store, room, folder, room_folder, pin, the agent_* log, terminal_tab)
and apps/app/lib/db/schema-multiuser.ts (auth, room_member, comments). The
hosted build uses the full schema and migration history (drizzle/); the desktop
PGlite backend migrates from the core half alone (drizzle/local, generated by
drizzle.local.config.ts). Headless keeps the multi-user surface, so its PGlite
runs the full drizzle/ history. The single local user is seeded on boot from
instrumentation.ts.
When you change schema-core.ts, generate the desktop migration alongside
the hosted one, from apps/app:
pnpm drizzle-kit generate --config drizzle.local.config.tsPGlite applies drizzle/local itself on boot, so there’s no migrate step.
Building it by hand
The desktop profile, apps/desktop/desktop.env, sets every flag together:
# Read at build time
SCREENPLAY_DESKTOP=1
NEXT_PUBLIC_SCREENPLAY_PROFILE=desktop
NEXT_PUBLIC_YJS_HOST=local
NEXT_PUBLIC_BASE_PATH=
# Read at runtime, and at build time so both agree
SANDBOX_BACKEND=local
SCREENPLAY_DB=pglite
BLOB_STORE=local-fs
AGENT_ENGINE=external
THUMBNAIL_CAPTURER=tauri-webviewpnpm --filter desktop build:sidecar builds the app with that profile. To do
the same yourself, run next build directly rather than the app’s build
script, which first migrates a hosted Postgres. The build opens PGlite once,
so point it at a throwaway folder:
cd apps/app
SCREENPLAY_DESKTOP=1 \
NEXT_PUBLIC_SCREENPLAY_PROFILE=desktop \
NEXT_PUBLIC_YJS_HOST=local \
NEXT_PUBLIC_BASE_PATH= \
SANDBOX_BACKEND=local \
SCREENPLAY_DB=pglite \
BLOB_STORE=local-fs \
AGENT_ENGINE=external \
THUMBNAIL_CAPTURER=tauri-webview \
PGLITE_DATA_DIR="$(mktemp -d)" \
npx next buildThe desktop shell sets the runtime paths and ports (PORT, the data folders,
TAURI_CONTROL_URL) at each launch. Each flag and path is described in
Environment variables.