Golden Image

Shipping and base updates

Upload the built ZIP to Mothership, create new apps from pinned profiles, and update the base (SDKs, build tools) while keeping what app authors changed.

Uploading to Mothership

Configuration What to do
Frontend-only (recommended) Upload frontend/dist/<release>.zip in Work apps → Catalog → Add app. It becomes a candidate; apply it to shared validation and production in Versions & environments
Frontend + backend Upload the ZIP and connect the backend with External backend connection · advanced. Install per environment and choose the audience
Backend-only Connect the backend by URL and signing key

Declared record_schema / value_schema documents are enforced by the gateway on every write. The full flow is in Mothership: shipping apps.

With Galpi

Connect a Galpi project to a Mothership app and the chat's agent changes this repository and Galpi sends the source to Mothership. Mothership's source build executor builds it, and Galpi asks for previews and review candidates from that build. A new app's first source and base updates use the approved profile list the Galpi operator sets with GALPI_MOTHERSHIP_PROFILES_FILE. Everything also works without Galpi, with the CLI and ZIP uploads. → Connecting the products

New apps from official profiles

A profile pins one version of the base. The default profile is minimal (a minimal frontend app); choose the document review example with --frontend-profile document-review, and Python or Node with --runtime backend or --runtime backend-node.

bash
python scripts/template_profiles.py pack . /tmp/profile-v1 --version 1.0.0
# use the SHA-256 it prints
python scripts/template_profiles.py verify /tmp/profile-v1 --sha256 HASH
python scripts/template_profiles.py init /tmp/profile-v1 /tmp/my-app --sha256 HASH --package-slug sales-desk
  • The profile digest is the SHA-256 of profile.json (lower-case hex). Mothership's approved list and Galpi's list compare against it as is.
  • --package-slug sets app ids by Galpi's rule: the frontend agent.id is <slug>, the backend's <slug>-backend. Mothership source builds need the frontend agent.id to equal the app's packageSlug.
  • The app's .mothership-template.json holds the generating profile digest and the baseline of managed files. SDKs, contracts and build scripts are managed; product source and the app manifest belong to the app's authors.

Base updates

bash
# commit your work first, then on a separate branch
git switch -c update/mothership-v2
python scripts/template_profiles.py update /opt/profiles/v2 . --sha256 HASH
make build && make check && make test

After an update every managed file is byte-for-byte the new profile's.

  • Managed files the app didn't change get the new content. A managed file the app changed is updated only when a 3-way merge comes out exactly as the new profile's file.
  • With any conflict nothing changes: .mothership-update/conflicts.json and the new profile's files (.mothership-update/<path>) are left for you. Move app-specific changes into app code or AGENTS.md and run the same command again.
  • Updates stay within one contract major version; there's no automatic move to another major.
  • When a Mothership operator sets MOTHERSHIP_REPOSITORY_PROFILES_FILE, source builds accept only apps from an approved profile with managed files intact.

Air-gapped customers

Golden Image profiles are published centrally and imported at the customer. The release manifest pins the release id and sequence, the source commit, every profile's id, version, digest, parts and contract version, the supported Mothership and Galpi range, image and package digests and the SBOM. Content is never replaced under the same version label. What source alone can't carry (npm dependencies, fonts, build images) and wiring to the customer's internal addresses are in the repository's docs/air-gapped-distribution.md. Apps fetch nothing from a CDN, so the same build runs on a closed network.

Esc