The manifest is the contract between your app and the platform: it declares what your app is, how to run it, and what data it’s allowed to ask for. You never hand-write the JSON. Both SDKs give you constructors that produce it, and dip app new scaffolds a starting manifest for you. It’s materialized to a manifest.json file that’s byte-identical however it was produced, which is what lets the platform detect drift between your source and what you last built.

Top-level fields

Pin source to a plane-local repository

An app version can record source provenance from a same-tenant plane-local Git repository. The Git source is metadata, not a build request. Continue to supply the executable image through the existing pushed-image or bring-your-own-image flow. The plane_git entitlement and your current repository role are checked when you bind a new source. GitHub and GitLab URLs are not accepted because Dippr does not mirror external repositories.

Components

Today your manifest has exactly one component: the container that runs your app.
A component’s role is always service in v1. worker and job are reserved for a future run-as-owner mode and are rejected if you declare them today.

Static apps

A browser-only app, like the one dip app new --runtime frontend creates, has nothing to run on a server. It is a folder of HTML, JavaScript and CSS. Declare that folder as staticRoot and Dippr serves the files for you:
When the app is installed, Dippr reads the folder out of your pushed image and serves it from its own file server. Your image is never started, so it needs no server, no start command and no user: the frontend template’s image is FROM scratch plus the built folder. The rules for staticRoot:
  • It is an absolute path other than /, with no . or .. parts, no trailing slash, and at most 256 bytes.
  • It goes on the component that serves the app’s pages, and that component sets no image, command, args or env.
  • The folder holds only regular files and folders. A symbolic link, hard link, device or FIFO anywhere under it stops the install, and so does a file, link, device or FIFO in place of any folder above it.
  • The folder holds an index.html at its top. Each file’s path inside the folder is at most 1,024 bytes and has no backslash (\).
  • It holds at most 2,000 files and 16 MB in total, and the files must compress to 900 KB or less. These limits fit a typical single-page app many times over. The file and byte counts include every copy of a file that the image’s layers write under the folder, even a copy that a later layer replaces or deletes, so build the folder in one layer.
  • The image is pushed with gzip-compressed layers, which is what docker buildx and dip app push produce. An image whose layers use zstd or no compression is refused.
  • The platform reads the image’s layers to find the folder, and stops after 2 GB of uncompressed layer content in total, counting what is outside the folder too. Build the static app on a small base image, or on none, as the template does.
What your visitors get:
  • / serves index.html. A path with no file extension that matches no file also serves index.html, so links into your app’s own pages work after a reload. A missing file with an extension, such as /missing.js, is a 404.
  • The folder’s files answer only GET and HEAD. The page’s queries are separate requests to the platform, described next, and work as in any app.
  • The app’s queries go through the same /.altimate/ addresses as any app, so each visitor still sees only the rows their own access allows.
A path that breaks the rules, or an image, command, args or env beside staticRoot, is refused before anything is installed: dip app check reports it, and the platform refuses to register that version. A folder that breaks the rules ends the install as Failed, and its message names the file or layer and the rule. Fix the image, push a new version, and select that version on the installation. An app published before its template declared staticRoot keeps running as a container until you push a new version of it and select that version on each installation. See Versioning.

Routes

Routes map a URL path, on your app’s own host, to the component that serves it:
  • Up to 16 entries. Paths must be unique, but one component can back any number of routes.
  • Matching is longest-prefix.
  • There’s no path rewriting: a request to a path such as docs/x arrives at your component exactly as written, unchanged.
  • Omit routes entirely and the root path is routed for you.
  • The /.altimate/ prefix is reserved for the platform’s own endpoints (identity and the same-origin engine proxy) and can never be routed to your app. Browser code uses /.altimate/engine to query; POST /.altimate/token is refused.
Every installed app page can load assets and make browser API requests only to its own Dippr app origin. Bundle assets with your app; external APIs and CDN assets are blocked. A manifest cannot relax these restrictions. See What can an app page load or call?.

Capabilities

Capabilities are the data your app asks to access, and they’re what an admin reviews and consents to at install time. In v1, only kind: "data" is accepted:
Leaving a segment empty widens the scope. Catalog alone means catalog-wide; catalog and schema means schema-wide; all three means exactly one table. Each capability reduces to one canonical, positionally-parsed string, data:<catalog>:<schema>:<table>:<read|write>, which is what an installation’s consent is actually checked against. You never write this string yourself; the SDK constructors and the server both derive it from the structured fields above, so it can never disagree with what you declared. Declaring both a wide capability and a narrower one it already covers (say, catalog-wide read on lakehouse alongside a schema-wide read on lakehouse.sales) is rejected. Declare the one that says what you mean.

What gets rejected, and why

Both SDKs run the same checks at authoring time that the server runs again at registration, so you find a mistake at dip app check rather than at push:
  • An id that isn’t a valid slug, or a version that isn’t semver.
  • A capability written in the flat, non-nested shape. An early draft of this guide showed it, and it’s rejected by name rather than silently accepted as a second valid spelling.
  • A capability with no reason, or one over 200 characters.
  • A table without a schema.
  • More than one component, more than 16 routes, or more than 8 declared engineKinds.
  • A route under /.altimate/.
  • An environment key named PORT, HOME, or prefixed ALTIMATE_.
  • An unrecognized schemaVersion. An old server refuses a manifest shape it doesn’t understand, rather than half-parsing it.

Versioning

version must increase when you change the app’s code. An unchanged rebuild that runs the same platform images can keep its version, even when the image index has a different digest. A version number identifies a published release you can select. An installation also records the exact image and manifest selected for it. Publishing another version or rebuilding the same version does not replace that selection. Consent, retries, and wake follow the installed selection until you explicitly choose a different version. Every published version is retained, so you can roll an installation back to an older release. See Build and push an image for the publish flow and Install an app for version selection and rollback.

One component today

The manifest schema models components as a list of up to 8, and the platform will grow to run multiple containers per app, but registering or installing a manifest with more than one component is refused today, naming this as a roadmap limit rather than a parse error. An app deploys as a single pod.

A complete example

manifest.json

Build a data app

Scaffold an app and read who’s calling it before you write a manifest by hand.

Build and push an image

Publish a new version once your manifest is ready to ship.