khaos storage goes live

api.khaosstorage.com went live on 2026-05-07. it is a git plane for KSPD projects, a content-addressed store for generated media, and a cross-product event spine — all on one domain, all behind the same Cognito user pool that fronts app.khaosmachine.com.

the decision that made this possible was deciding not to build a custom storage system. the Khaos Storage team built the git plane using the smart-HTTP wire protocol via go-git. server-side parse-on-create means every kspd push seeds a full parsed.json and story.json on arrival. the platform gets structured story data without a separate indexing job. the design is not novel — git as the source of truth is the oldest trick in the book — but applying it to KSPD projects required treating the screenplay format seriously enough to parse it at the wire boundary, not at read time.

the identity model took more thought than the storage model. khaos.machine and Khaos Storage are two products with two domain names and two user-facing surfaces. they share one Cognito user pool (us-east-1_OomuH51rE). the practical consequence: a user who signs in at app.khaosstorage.com and a user who signs in at app.khaosmachine.com are the same identity. cross-product SSO comes for free without a separate federated layer.

cloud sync is opt-in and off by default. a project without a storage block in its info.json stays local forever — existing behavior unchanged. a project with the block routes to the configured host. the knob is per-project, not per-installation. one screenwriter can keep three projects local and one on storage without reconfiguring the application.

the CLI workflow

the CLI surface was designed to match what git users already know, because KSPD repos carry the same operational contract as any git-tracked project.

khaos-tools kspd clone <url> creates a local KSPD backed by a remote origin. the implementation calls git.PlainClone with bearer auth transport injecting Authorization: Bearer <APIKey> on every smart-HTTP request. when the remote repo is empty — which it will be on first clone of a freshly created storage slot — the command handles transport.ErrEmptyRemoteRepository cleanly: it initialises a local repo and registers origin so the next push populates it. the empty-remote case is not an error; it is the standard onboarding path.

khaos-tools kspd push calls repo.Push with the same bearer auth transport and treats git.NoErrAlreadyUpToDate as success, which means re-running push in a script is safe. credentials resolve in order: environment variables (KHAOS_STORAGE_API_KEY and KHAOS_STORAGE_ENDPOINT), then ~/.khaos/storage.json (mode 0600), then a hard error with instructions to run khaos-tools storage login. the login command calls POST /v1/bootstrap-key and writes the returned key to the credentials file. the pattern mirrors ~/.khaos/keys.json for LLM keys — same discovery logic, same file discipline, no secrets in environment or command-line history.

khaos-tools kspd link <project-path> <owner>/<repo> connects an existing local KSPD to a freshly created remote slot. it stamps the storage block into info.json and registers origin. link is the right command for a screenwriter who started a project before the storage bridge existed. they do not need to re-create the project or lose local history — link threads the remote in.

kspd checkpoint — already the standard command for committing a local snapshot — gains an automatic post-commit push when info.json carries a storage block. the push is best-effort: the local commit always succeeds first; a failed push warns on stderr but does not roll back the local commit. the design reflects a deliberate sequencing choice: local durability is not contingent on network reachability.

raw git clone against storage URLs is intentionally unsupported. the git CLI sends HTTP Basic; the storage auth surface accepts Bearer and API-key only. this is not an oversight — KSPD repos carry schema, identity, and event semantics that the workspace CLI is the right gatekeeper for. pushing a KSPD through a raw git client would bypass the parse-on-create hook and produce a storage repo with no parsed.json or story.json. the CLI gap enforces correctness.

what changed for users

what changed for users on 2026-05-12 is small by surface area but large by capability class. cloud backup now exists. collaboration paths are unblocked — two writers can push from separate machines to the same origin and pull changes without a manual file-transfer step. generated media (once the synthesis pipeline completes) can leave the local machine without a manual export step, routed to the content-addressed asset store at POST /v1/assets. the Khaos Storage arc is not finished — the repo-list view, the media upload path, the “save to storage” flow from the playground — but the ground is down. the rest is surface on top of a solid contract.

the composition.completed event is the first cross-product signal. when khaos-wfl full-analysis completes on a storage-backed project, it emits a best-effort KVE event to /v1/events. the payload carries scene_count, character_count, tools_version, and duration_seconds — enough to populate a storage-side activity feed without leaking screenplay content. no screenplay text crosses the event spine. the event fires non-blocking; if the storage API is unreachable, the analysis result is not affected.

related engineering posts: khaos storage goes live — git plane, assets, and hosted shell