Skip to main content

Building a custom app

The Custom Apps V2 lifecycle: create, check out a workspace, edit with autosave, flush, publish, and poll the build — plus rollback and the read-only kit.

The decision: you are building or editing a hosted custom app from a script or an agent. What is the safe edit-to-live loop?

The lifecycle​

  1. Create the app with autessa.customAppsV2.create (or autessa.customAppsV2.clone from an existing one). Create hands you back a workspaceId — a ready-to-edit workspace (handle ws-1) already checked out — so you can start editing immediately. Workspace ids are friendly handles like ws-1 (the raw UUID also works everywhere).
  2. Check out an additional private server-side workspace with autessa.customAppsV2.workspace.checkout — only if you need a second/fresh working copy; create already gave you the first. Checkout returns a workspaceId handle (e.g. ws-2) plus the editable files and the read-only files. A workspace is a copy-on-write working copy of the draft, isolated from the browser editor.
  3. Edit inside the workspace. Every write, delete, and rename autosaves immediately into the workspace tree — there is no separate save step. Use autessa.customAppsV2.workspace.files.write, .delete, .rename, or the atomic autessa.customAppsV2.workspace.applyChangeSet for a multi-file change.
  4. Check your work with autessa.customAppsV2.workspace.status — it reports what you added, modified, deleted, or renamed, and whether the shared draft drifted underneath you.
  5. Flush with autessa.customAppsV2.workspace.flush to project your changes onto the app's shared draft and tear the workspace down. Conflicts (the draft changed while you edited) surface here; the default is to fail on conflict rather than clobber.
  6. Publish with autessa.customAppsV2.workspace.publish (flush + build in one step) or autessa.customAppsV2.publish on the already-flushed draft.
  7. Poll the build with autessa.customAppsV2.buildStatus. Polling is mandatory: the first poll that sees SUCCESS finalizes the publish. On FAILED, the status carries a build log excerpt so you can read the error and fix the file — closing the edit→publish→fix loop.

Decision rules​

  • Agents and scripts edit through a workspace; the browser editor edits the draft directly. Checkout keeps your automated edits isolated until you deliberately flush.
  • src/autessa/** and the lockfile are read-only. Those files are the app's SDK kit and its pinned dependencies — reading them teaches you the app's available surface, but writes are refused.
  • Discard, don't leave it open. If you abandon an edit, call autessa.customAppsV2.workspace.discard — it deletes the working copy and leaves the draft untouched. Idle workspaces expire on their own, but discard is immediate and explicit.
  • Roll back a bad publish with autessa.customAppsV2.rollback, which restores an earlier version's source onto the draft.

Worked example​

Check out the app (autessa.customAppsV2.workspace.checkout), write the changed files (autessa.customAppsV2.workspace.files.write), confirm the diff (autessa.customAppsV2.workspace.status), then autessa.customAppsV2.workspace.publish and loop on autessa.customAppsV2.buildStatus until SUCCESS. If it returns FAILED, read the log excerpt, re-check-out, fix the file, and publish again.

See also​

  • data-placement — the AutessaDB tables a custom app reads and writes.
  • sharing-permissions — who can edit and publish an app, and the app's table security.