khaos machine without the install

until 2026-05-08, using khaos.machine required a desktop install. the .pkg or .deb, the khaosd daemon in the background, the menu bar icon. that was the right trade for the first year — a locally-running binary with full filesystem access is the correct architecture for a tool that reads .fountain files and produces multi-megabyte analysis artifacts. it is not the right answer for a screenwriter who wants to paste a scene and ask a question.

app.khaosmachine.com is the web-accessible surface for that use case. it ships as a static bundle on CloudFront + S3, meaning there is no server-side rendering, no dynamic origin to maintain, and no per-request cost for users who are just browsing. when a user signs in, the page talks to the parser Lambda at api.preview.khaosmachine.com and to Khaos Storage at api.khaosstorage.com directly. khaosd is not involved.

what shipped on day one was narrowly scoped by design. sign-up and sign-in via Cognito. the Fountain playground: paste or type a .fountain scene and run the parser against the Lambda API. the deeplink receiver for storage-side “Open in Khaos Machine” CTAs. a PWA manifest and service worker, so the page is installable to a home screen on mobile or desktop. that is the floor for a useful surface, not a full-featured application.

the KHAOS_RUNTIME flag

the KHAOS_RUNTIME flag is how eight Nuxt apps — originally built to run behind a locally-running khaosd daemon — become web-native without forking the codebase.

the flag is a compile-time constant, not a runtime branch. when it is set during the production build, the app loads a different client module: one that routes API calls to the Lambda and to Khaos Storage directly, rather than to localhost:<dynamic-port>. the client module swap happens at the import boundary — all the app’s composables and views stay identical. the app does not know at runtime which client it is using; it calls the same interface either way.

this matters because the alternative — branching on KHAOS_RUNTIME at call sites throughout the codebase — would have made the hosted and local codepaths diverge over time. every new API endpoint would require two cases. the module swap approach keeps one codebase with two compile targets: local, where the app expects khaosd, and hosted, where the app expects Lambda + Storage.

the practical consequence for the playground specifically: the parser Lambda at api.preview.khaosmachine.com accepts the same .fountain input the local CLI accepts. a user who pastes a scene into the playground gets back the same structured output — elements, scenes, characters, locations — that a user running a local full analysis sees in the dashboard. the Lambda is not a demo endpoint; it is the same khaos-tools parser binary packaged for a serverless runtime.

multi-app hosted routing and why it matters now

what did not ship on 2026-05-08 is multi-app hosted routing. the dashboard, the story player, the projects view — those apps depend on khaosd for their primary data path: job results, compositions, scene analyses. hosting them without khaosd requires either the Lambda to serve those endpoints (partial) or Khaos Storage to expose a repo-list endpoint the browser can query. neither was ready on day one.

the auth layer had to ship first, and that sequencing was correct. the Cognito setup — shared user pool us-east-1_OomuH51rE across app.khaosmachine.com (client 6i6uc4mlc33umis6en8nj5eps1) and app.khaosstorage.com (client 4sjntei2ivrqfqpmqosg7uiut1) — is the structural prerequisite for everything that follows. multi-app routing is a routing problem once identity is solved. it is an identity problem otherwise, and identity problems get worse the later you solve them.

the same sequencing logic applies to the PWA manifest. a service worker that caches the playground is useful on day one. a service worker that caches project data needs the project data to exist in a browser-accessible form first. shipping the manifest now means that as the hosted app gains more surface, users who installed it to their home screen get updates without re-installing.

the architectural commitment

the architectural commitment the hosted shell represents is larger than the feature list. it means the platform has a web-first integration surface that is publicly reachable, accountable for uptime, and gated by the same Cognito identity as Khaos Storage. partners and integrators who want to send a user to khaos.machine without requiring a desktop install now have a path. prospective users who want to try the parser before committing to an install have a path. mobile devices that cannot run khaosd have a path.

the auth layer, the playground, the PWA surface — these are the structural preconditions for everything that follows. what shipped on 2026-05-08 is the foundation. the multi-app hosted experience is the next concrete milestone, and it builds directly on this.

related engineering posts: parser API goes Lambda — khaos-tools stateless on the cloud, khaos storage goes live — git plane, assets, and hosted shell