Skip to Content
Self-hostingHeadless

Headless

Headless

Headless runs Screenplay from a clone of the repository on a machine you control, usually a remote Linux dev box. One command checks the machine, builds the app in production mode and serves it. You reach it from your own computer over an SSH tunnel, as the host: the only person who writes.

It uses the same local backends as the desktop app: embedded Postgres (PGlite), the local Yjs host, files on disk, a git worktree for each chat, and the coding CLIs and gh installed on the machine. Thumbnails are taken with headless Chrome.

Run it

Install the prerequisites

  • Node 22 or later, and pnpm
  • git
  • Python 3, make and g++, to build the terminal module (details)
  • Chrome for thumbnails: Puppeteer downloads one during pnpm install, or set CHROMIUM_PATH
  • at least one coding CLI, signed in: Antigravity, Claude Code, Codex or OpenCode
  • the GitHub CLI, gh, signed in

Clone and install

git clone https://github.com/zschiller/screenplay.git cd screenplay pnpm install

Set its environment

Optional. With nothing set, the data folder is ~/.screenplay/headless and the host listener’s port is 4100. Every variable it reads is below.

Start it

pnpm headless

It names each missing prerequisite and stops, so you can fix the machine before anything is built. Then it builds, starts, and prints how to reach it:

Screenplay is running (Headless). Host: http://localhost:4100 Frames: http://*.localhost:1355 (portless) From your own computer, open a tunnel to both ports, then the host URL: ssh -N -L 4100:127.0.0.1:4100 -L 1355:127.0.0.1:1355 you@devbox

Open the tunnel

Run the printed ssh line on your own computer, then open http://localhost:4100.

pnpm headless --no-build serves the last build without building again.

Listeners and the tunnel

The host listener listens on 127.0.0.1 only, so nobody else on the network can reach it: whoever has a tunnel to it is the host. It serves the app and its live connections (the canvas sync and the terminals) on one port.

Your own frames load through portless, which the local backend already runs each preview under. Each chat’s preview is registered with portless and loads at http://screenplay-<port>.localhost:1355, so the tunnel needs just two ports, the host listener and portless’s 1355, however many chats are running. Browsers send every *.localhost name to your own computer, which is where the tunnel picks it up.

Restarts

Nothing keeps the server running. When the machine stops (an idle stop, a reboot), run pnpm headless again: canvases, chats, files and previews come back from the data folder, and previews restart when their canvas opens.

The data folder holds:

Folder or fileWhat
pglite/The database
yjs/Each canvas’s live document
blobs/, files/Thumbnails, and files on canvases
worktrees/Each chat’s code
coordinator/Each canvas’s Coordinator folder
secrets.jsonKeys minted on first start; keep it with the rest

Changing what it runs

Headless runs the same built-ins as the desktop app: gh-cli GitHub access and every coding CLI the machine has. GitHub access is picked by a select module in the repo, which GITHUB_ACCESS can override. A company setup that needs more, like a gh wrapper, GitHub Enterprise or an internal CLI, changes the code in a fork.

The terminal module

The terminal runs on node-pty, a native module. There’s no prebuilt copy for Linux, so pnpm install compiles it with node-gyp, which needs:

  • Python 3
  • make
  • a C++ compiler (g++ or clang++)

On Debian or Ubuntu, sudo apt-get install python3 make g++ covers all three.

Environment

pnpm headless sets everything the server needs. You can also set:

VariableDescription
SCREENPLAY_DATA_FOLDERWhere Screenplay keeps its data. Default: ~/.screenplay/headless
SCREENPLAY_HOST_PORTThe host listener’s port. It always listens on 127.0.0.1. Default: 4100
GITHUB_ACCESSgh-cli (the default) or oauth-account. See GitHub access
CHROMIUM_PATHThe Chrome thumbnails use, instead of Puppeteer’s
PORTLESS_STATE_DIRWhere portless keeps its routes. Default: ~/.portless
Last updated on