Skip to Content
Self-hostingConfigurationLocal (single-user) build

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_member collapse 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:

ProfileIdentityMulti-user surfaceMac appViewers
hosted (default)accountonoffoff
desktophostoffonon
headlesshostonoffoff
  • Identity is who writes. account is many people signed in with GitHub. host is 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.ts

PGlite 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:

apps/desktop/desktop.env
# 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-webview

pnpm --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 build

The 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.

Last updated on