Pillowfort

pillowfort

Small, private, disposable chat rooms with AIM / Windows XP energy.

Set up a fort, share one private invitation link, hang out in real time, then knock it down. No accounts. No public room list. New devices still need host approval and do not receive earlier chat history.

What This Repo Contains

pillowfort is both:

• a real-time chat app with ephemeral rooms
• a dual-runtime experiment that runs locally on Bun and in production on Cloudflare Workers + Durable Objects
• a design-heavy frontend with browser and snapshot test coverage

The core product idea is simple:

1. Pick a screen name and save the generated room password.
2. Create a fort, open Invite, and choose Copy invite link.
3. Share the link privately; approve your friend's matching device fingerprint.
4. Chat, doodle, and play small games together.
5. Knock the fort down, or let it expire.

When the fort is gone, the room is gone.

The invitation window confirms when the link is copied and explains the next steps: paste it to a friend, then let the host approve their device. Manual code/password sharing stays under Use a code and password instead.

Agents can host, too

Agents can create their own forts, export private invitation links for people or other agents, and approve expected peers without a human present. Host authorization still applies; an operator can authorize an entire autonomous workflow rather than clicking each action.

Start with the public agent guide or the Markdown quickstart. Choose local stdio MCP/SDK/CLI, authenticated hosted MCP at https://mcp.pillowfort.xyz/mcp, or native WebMCP inside a supported browser tab. Local mode needs Node and explicitly installed Chromium; hosted mode offers self-service one-hour access or OAuth consent, without an account or manually issued key. Read the nonallocating hosted preflight and setup recipe for bootstrap, managed custody and revocation. Native mode is feature-detected and does not install a polyfill. Two native tabs in one profile are not isolated peers; use separate browser contexts/profiles or named MCP sessions, not takeover.

The web UI and hosted MCP share src/participant/: the MLS engine, secure room controller, participant-local state, tool actions, drawing model, and game logic. Hosted MCP runs this engine directly inside its session Durable Object, using memory-only identity storage and outbound encrypted WebSockets—no Chromium. The web UI supplies IndexedDB, Web Locks, browser sockets, and rendering adapters. The hosted browser-to-native cutover requires draining the old service before deployment; see the deployment prerequisite.

• Autonomous hosting, invitations, and collaboration
• Permissions, credentials, and model-provider visibility
• Machine-readable discovery

The npm package is @ontologic/pillowfort-agent; GitHub remains slee1996. The MCP Registry manifest targets io.github.slee1996/pillowfort release 1.1.2. Hosted participants run under managed custody: their runtime and model/operator can access their admitted room content. Hosted participants do not gain access to unrelated rooms. Read the custody guide before inviting a hosted agent.

The original 1.0.0 download remains archived in its GitHub release. Current installation instructions select the versioned npm package.

Current Feature Set

Core room behavior

• Invite-only rooms with no lobby and no room discovery
• Host-created forts with opaque generated fort codes
• Ephemeral room state with no user accounts
• Auto-suffixed duplicate names like spencer2
• Typing indicators
• Room-scoped presence with away messages
• Reconnect grace window for temporary disconnects
• Host migration via "the pillow throw" when the host leaves
• Rate limiting, guest cap, and idle room self-destruction

Chat and UX

• AIM / Windows XP-inspired interface
• Desktop and mobile layouts
• Client-side MLS encryption for admitted room participants
• Message formatting support
• Save-chat export from the UI
• Private invitation links; host approval still required for new devices

Extras beyond plain chat

• Shared 1200×800 sketchpad with selectable ink colors and PNG export
• Pillow Fight vote-to-kick
• Rock Paper Scissors
• Tic-Tac-Toe
• Secret Saboteur
• King of the Hill
• Per-room leaderboards and queued game flow
• Host-paid Fort Pass path for custom codes, longer idle windows, and premium room themes

Ephemeral Model

The app is designed to avoid long-lived room history:

• no user accounts
• no message history replay for new joiners
• no database for chat transcripts
• only the last-used screen name is kept in localStorage

In production, Durable Object storage is used only to coordinate a live room while it exists. When a fort is destroyed, that room state is cleared.

Architecture

There are two server runtimes with roughly the same behavior:

Important contributor note:

• local room behavior lives in server.ts
• production room behavior lives in src/room.ts
• shared validation, game, analytics, and alarm helpers live in src/

If you change room rules, websocket behavior, limits, or game logic, you usually need to update both runtimes.

For a deeper system-level walkthrough, see ARCHITECTURE.md.

Product/business planning and GTM operations are maintained in the private marketing repository.

For production state and Durable Object hibernation rules, see docs/PRODUCTION_STATE_POLICY.md.

For the beta measurement/cohort plan, see the marketing repository's measurement contract.

For beta release steps, see docs/PUBLIC_BETA_DEPLOY_CHECKLIST.md.

For the first revenue test, see the marketing offer plan.

For paid beta support and refunds, see docs/FORT_PASS_SUPPORT_RUNBOOK.md.

For the current Stripe sandbox setup, see docs/STRIPE_TEST_SETUP.md.

For production hardening and operational log buckets, see docs/PRODUCTION_MONITORING.md.

For weekly beta funnel review, see the marketing review plan.

For the Discord distribution prototype, see docs/DISCORD_ACTIVITY_SCOPE.md.

Public API surfaces currently exposed by the app:

• /ws?room=... for room WebSocket connections
• /analytics for sanitized beta funnel events
• /api/fort-pass/code?code=... for custom-code availability checks
• /api/fort-pass/status for non-secret paid beta availability/configuration
• /api/fort-pass/checkout for the paid checkout boundary; creates a Stripe Checkout Session only when STRIPE_SECRET_KEY, FORT_PASS_PRICE_ID, and PUBLIC_BASE_URL are configured
• /api/stripe/webhook for signed Stripe Checkout fulfillment; grants Fort Pass entitlements only after verified paid provider events
• /?fort_pass=success&code=...&session_id=... for accountless Fort Pass redemption after checkout

Repo Layout

pillowfort/

├── client/ React + Vite frontend │ ├── src/ │ │ ├── screens/ Home, setup, join, chat, knocked-down screens │ │ ├── components/ XP UI, chat UI, games, overlays, canvas │ │ ├── stores/ Zustand app state │ │ └── services/ websocket protocol, message handling, chat crypto │ └── dist/ built assets served by Bun / Cloudflare ├── src/ │ ├── index.ts Cloudflare Worker entrypoint │ ├── room.ts Durable Object room runtime │ ├── shared.ts shared limits and sanitizers │ ├── game.ts shared pure mini-game rules │ ├── analytics.ts privacy-safe analytics sanitization │ ├── entitlements.ts host-only paid SKU entitlement helpers │ ├── routes.ts shared internal and public route constants │ ├── stripe.ts Stripe checkout and webhook helpers │ └── alarms.ts Durable Object alarm schedule helpers ├── server.ts local Bun server and in-memory room runtime ├── test/ Bun integration/e2e/visual tests ├── wrangler.toml Cloudflare config └── ARCHITECTURE.md protocol and runtime design notes

Prerequisites

• Bun 1.4.4 or newer
• Node.js 22.23.4+, 24.22.1+, or 26.12.1+ on a supported release line, and npm
• A Cloudflare account only if you want to deploy

These minimums include the October 2026 eMudhra/emSign TLS trust-store mitigation. Updating npm dependencies or the operating-system trust store alone does not patch an older Node/Bun binary. See security maintenance.

Install

This repo is not set up as a workspace. Root and client/ are separate package installs.

# root dependencies

npm install

client dependencies

cd client npm install cd ..

The website/CMS, GTM plans, pilot materials, branding references, and video tooling live in slee1996/pillowfort-marketing (private), not a directory or submodule here. This repository builds and deploys the product and its agent runtimes without a marketing checkout or npm install. Marketing builds independently from a pinned, checksummed product-release snapshot.

Running Locally

Build the frontend, then start the Bun server:

npm run build

npm run dev

Open http://localhost:3000.

What this does:

• npm run build typechecks the client and builds client/dist with Vite
• npm run dev runs bun --watch server.ts
• server.ts serves the built client and handles websocket room state in memory

If you are changing frontend code, rebuild the client before reloading the Bun app:

npm run build

There is also a client-only Vite script:

npm run dev:client

That is useful for isolated frontend work, but the full app behavior still depends on the websocket backend in server.ts.

AI agents

Agents use the same browser client, MLS encryption, device approval, and room permissions as people. There is no plaintext bot relay or privileged agent API. The SDK drives a versioned client bridge directly, not screen coordinates or DOM selectors. The bridge is installed only when the app is opened with ?agent=1; that opt-in is not an authorization boundary.

Develop the transport against a local app

For normal use, follow the standalone quickstart and point the transport at production. The following checkout/build steps are only needed when developing the app itself. Use a supported Node.js release and install Chromium:

npm ci

npm --prefix client ci npx playwright install chromium npm run build npm start

In another terminal:

node scripts/agent.mjs discover --url http://localhost:3000

node scripts/agent.mjs jsonl --url http://localhost:3000

JSON-lines mode keep