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.
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-slugsets app ids by Galpi's rule: the frontendagent.idis<slug>, the backend's<slug>-backend. Mothership source builds need the frontendagent.idto equal the app's packageSlug.- The app's
.mothership-template.jsonholds 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
# 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.jsonand the new profile's files (.mothership-update/<path>) are left for you. Move app-specific changes into app code orAGENTS.mdand 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.