Headless
HeadlessHeadless 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,
makeandg++, to build the terminal module (details) - Chrome for thumbnails: Puppeteer downloads one during
pnpm install, or setCHROMIUM_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 installSet 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 headlessIt 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@devboxOpen 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:
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++orclang++)
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: