Ship

Docs

Ship sends signed text, images, flags and popups to the apps you have already shipped, without a store release. It changes content and configuration only, never code.

Ship is in early access. It is not self-serve yet: workspaces and API keys are issued after you request access. The iOS package and the ship command line are provided with your workspace.

How it works

You put files in a folder, run one command, and your app picks them up the next time it checks in. Every release is signed. The app checks the signature and the fingerprint of every file before using it, and ignores anything that does not match.

A release belongs to one app, one platform and one channel, a name you choose such as beta or prod. A publish replaces that platform’s whole release, so a release always contains everything you want live.

Set up

  1. Request access at /start. Once your workspace is ready we email you; sign in at /start to see it and reveal your API key (it starts with shp_ and is shown once).
  2. Install the ship command line. On macOS or Linux:
curl -fsSL https://ship.zynclave.com/install.sh | sh

It picks the build for your machine, checks it against the published SHA256SUMS and installs ship to /usr/local/bin if it can write there, else ~/.local/bin. Check it with ship version. To install by hand, or on Windows, download v0.1.0 for your machine, check it against SHA256SUMS, unpack it and put ship (ship.exe on Windows) on your PATH:

  1. Save your key. The command reads it from standard input and stores it for that API only:
ship login --api https://api.ship.zynclave.com

In CI you can set SHIP_API_KEY instead. The key is only ever sent to the API it belongs to.

Then run ship init --app myapp to write a starter ship.yaml, and adjust it. Every command reads ./ship.yaml unless you pass --file.

api: https://api.ship.zynclave.com
app: myapp
platforms:
  ios:
    runtime: ios-1.4.0
    assets: ota/ios
  android:
    runtime: android-1.4.0
    assets: ota/android

runtime names the app build the release is for, for example ios-1.4.0. Use your real app version, so that a payload never reaches a build that cannot render it. assets is the folder to publish, and every regular file in it becomes part of the release. An optional config entry points to a JSON file of key and value settings.

Release layout

Inside the assets folder, the app looks for these paths:

ota/ios/
  sdui/popups/spring-sale-2027.json   one home popup
  sdui/cards/new-feature.json         one feed card
  lottie/spring-sale.json             animations they use
  images/spring-sale.png              images they use

Definition ids are lowercase letters, digits and hyphens, up to 64 characters. Reusing an id for different content is a mistake: in the apps we ship today, devices remember which ids they have shown, so a changed popup needs a new id.

Commands

ship validate
ship publish --platform ios --channel beta
ship rollout --platform ios --channel beta --pct 100
ship rollback --platform ios --channel beta

A good first release goes out to a small percentage, then 100 once it looks right on a real phone.

iOS

The iOS Swift package is provided with your workspace; we do not publish a public package URL yet. Add it to your app, configure it with your app id, channel, runtime and the public key we give you, and the app will fetch, verify and apply releases on its own. If you ever need to pull everything back, ship revert tells devices to drop over-the-air content and use what is built into the app.

Android

Coming soon. The release format is the same, so content you write today carries over.

Popups and cards

A popup is one modal over the home screen. A card sits in a feed among posts. Both are described in JSON and drawn natively from a small fixed set of components the installed app already knows, so no code is downloaded.

{
  "schema": 1,
  "id": "spring-sale-2027",
  "audience": "all",
  "start": "2027-03-01T00:00:00+05:30",
  "end": "2027-03-31T23:59:59+05:30",
  "priority": 10,
  "closeButton": true,
  "body": {
    "type": "vstack",
    "spacing": 12,
    "padding": 16,
    "children": [
      { "type": "lottie", "src": "lottie/spring-sale.json", "height": 150, "loop": false },
      { "type": "text", "fallback": "Spring sale", "style": "title" },
      { "type": "text", "fallback": "Everything is cheaper until the end of March.", "style": "body", "maxLines": 3 },
      { "type": "button", "label": { "fallback": "See the sale" }, "style": "primary",
        "action": { "type": "web", "url": "https://example.com/spring-sale" } }
    ]
  }
}

Components

vstack, hstack, text, image, lottie, button, badge and spacer. A definition may have at most 40 nodes, nested at most 6 deep, and text is limited to 500 characters. Colors are theme tokens such as primary or onSurface, never hex values. Your app decides what each token looks like, so content matches your own theme.

Images and animations

Images and Lottie files must be part of the same release, under images/ and lottie/. There are no web URLs, so a definition cannot load or track anything you did not sign.

Keep Lottie animations near-square. Older iOS builds fit an animation into a square as tall as its height, so a wide animation renders small there while Android fills the width. A drawing about as tall as it is wide looks the same on both.

Actions

A button or card can open an https page with web, or dismiss. Deep links into your own app are set up with your workspace. Anything else is ignored.

Schedule and audience

start and end are checked on the device, as times with seconds and an offset, such as 2027-03-31T23:59:59+05:30. In the apps we ship today, a popup is shown once per id per device. Set audience to all, meaning everyone on the channel whose app can render it. Targeting specific people is not available to outside workspaces yet.

All or nothing

If a definition has an unknown component, a bad field or too many nodes, the app skips the whole thing instead of drawing half of it. That is why ship validate exists, and why ship publish refuses to upload a release that would be dropped.

Store rules

Apple and Google both forbid replacing compiled app code after review. Ship stays on the permitted side: it changes content and settings the app was built to read. A bug in native logic still needs a normal release, though a setting or the kill switch can contain it in the meantime.

Questions

Write to ship@zynclave.com.