Install the app you built
In the app directory, run:dip login as the person who published the app. Installation uses your human login,
even if an API key is set in your environment. A key-only session cannot install.
If your saved login lacks apps:install, run dip login <workspace-url> and approve that
capability. Approving the login does not approve an app’s requested access.
dip app install shows the exact published version, its requested access and the code-trust message.
Confirm once to install that selection. It prints a shareable link only after the exact image has
finished provisioning and the app is ready. The default wait is seven minutes; set --timeout 10m
for a longer wait. On failure, use the reported installation ID, error and retry command.
Who can open the link
Beside the link,dip app install tells you who can open it and what it reads, so you can pass that
on to the people you share it with. The text comes from the access the installation holds, not from
your manifest or an agent’s summary:
- Any member of your workspace who has the link can open the app. You cannot limit an app to some members.
- Each person’s queries return only the rows and tables their own access allows, within the access you consented to. That limit applies to queries, not to the app’s code: an app with a server can keep rows it has read and show them to someone else, so install only code you trust.
- The last line names each catalog, schema or table you consented to, and the version it applies to.
A pattern is named as one: the starter
data:*:::readreads asevery table in catalogs matching the pattern * (never a workspace database). The qualifier appears only when the catalog name in the pattern, up to its first., contains a wildcard. A pattern such assales_db.*can reach the workspace databasesales_db, so it carries no qualifier. An app that declares no data access says it reads no workspace data. - The text names no other person, role, row filter or member.
dip app install prints no link. It reports
stale_selection: installed access differs from the access you approved. Running dip app install
again does not show you that other access: it submits the access you approved again, replacing the
other change. To keep the other change instead, open the installed app in the console and review it
under Consent ceiling.
If the server cannot confirm which access the installation holds, dip app install keeps checking
until its --timeout, then prints no link and reports consent_unconfirmed. This does not mean the
access changed. Run dip app install again to resume the approved installation and confirm its access.
A read-only dip app status --json observation does not resolve unconfirmed consent.
If Google sign-in fails in an embedded client browser, try the same app link in your system
browser and sign in there. Installation readiness does not verify that browser sign-in works.
The installed app’s page in the console shows the same first two sentences above its consent ceiling
while the app is running. A parked or failed installation does not show them.
The next run resumes the same installation and checks your current permissions again. It preserves
the approved image and does not repeat unchanged consent. Publishing another version requires a
fresh confirmation before the installed version moves. A stale_selection error means the selected
image changed; review the new publication before approving it. No newest-version fallback occurs.
For an agent or script, dip app install --json returns confirmation_required with the selection,
access, trust message and confirmation value. Show those details to the person. Only after their
explicit approval, run dip app install --json --confirm HASH using that value. Do not substitute
login approval or existing data access for this confirmation. A successful result has state: ready,
app_url and explanation, the sentences above as a list; progress stays on stderr. app_url is
the link to share: for a static app it opens the app inside the
person’s workspace console.
If own-app installation is disabled, ask a role administrator to open Settings → Roles & permissions,
select your role, and choose Allow for App installs → Manage own apps. Publication uses
Data apps → Publish own apps on the same page. You do not need a broader Data engineer role to
install your own static app. An ownership refusal, missing login capability, quota or unavailable
service needs the remedy it names, rather than a role change.
The consent screen
Before an app can run, you review what it’s asking for:This app asks to act on behalf of each user who opens it, up to this ceiling. Every user still queries within their own grants. Consent can only narrow what a query is allowed to return.Above the checklist, a one-line summary tells you whether the app touches your data at all: either “Runs SQL on your data, as you, limited to what your roles already allow” or “Requests no access to your data” for an app with no data capabilities. Below that, one row per capability the app’s manifest declares:
- A chip for read or write.
- The scope, in the form
catalog.schema.table(a blank segment means “every schema” or “every table” within it). - The reason the app’s author wrote, shown verbatim in quotes. This is what you’re actually approving, so read it.
You can consent to a broad ceiling, such as every table in a catalog. Each viewer can still query
only the data their own grants allow within that ceiling. Installing an app does not grant viewers
additional data access.
Choosing a version, engine, and plane
On the install form, before the checklist:- Version. Defaults to the newest published version. Pick an older one and the checklist below updates to show exactly what that version asks for, which may be less than the latest.
- Engine. Which query engine the app queries. Defaults to your tenant’s default engine.
- Data plane. Which plane runs the app’s pod. Defaults to your tenant’s default plane.
- Idle timeout. How long the app can sit unused before it suspends. Defaults to the platform’s standard timeout; pick a longer or shorter one, or “Never suspends.”
Own-app management supports read-only versions. Installing or selecting a version that requests
write access is refused even if it was published before an ownership transfer or role change.
Broad app administrators can manage writable versions.
What happens after you install
If your consent fully covers what the app declares, the installation moves through Installing to Active on its own. This takes a little while, since the plane is standing up a pod for it. If you left anything unchecked, it stays in Pending consent and nothing runs until you fix that. If it fails during provisioning, the detail page shows Install failed with the reason and a Retry install button.Updating consent
Open the installed app and click Update consent to review the installed version’s manifest and change which capabilities are granted. The ceiling changes at the query engine on its next policy check, without restarting an active app or minting a new token.- The request you submit is the complete desired set. Leaving a previously-granted capability unchecked revokes it; nothing is merged from what was there before.
- The checklist always shows what the installed version declares. Publishing a newer version does not change the access you are reviewing or move the installation to that version.
- If your new set still covers everything the installed version declares, it’s applied in place. If it no longer covers everything, the installation drops back to Pending consent.
- If someone changes the installed version while you are reviewing consent, saving is refused. The checklist refreshes to that version and resets your choices. Review it before saving again.
Changing version
Open the installed app and click Change version to move it to a different published version: upgrading, or rolling back to any older version that was ever published. This is one action either way. The installation is re-provisioned from the version you pick, and its consent ceiling is recompiled from that version’s manifest, not from what’s running now.- The version you’re currently on is marked, and each other version is labeled upgrade or rollback relative to it.
- Picking a version shows what it asks for. Rolling back to an older version may ask for less than what’s currently granted; moving to a newer one may ask for more. Either way, you’re re-confirming consent for that specific version before the move happens.
- If a newer version has been published, a banner tells you so on the installed app’s detail page, with a shortcut into this same dialog. Publishing a new version never moves an installation on its own. Every installation keeps the image and manifest selected for it.
- Retrying the installed version keeps its existing image, even if the author has rebuilt and published that same version number. Choose a different version to move the installation.
Waking and parking
An installed app suspends after its idle timeout and wakes again automatically the next time someone opens it. With permission to manage this app, you can also:- Park it: takes it down immediately and keeps it down. A parked app does not wake on the next request; only clicking Wake brings it back. Any open session ends.
- Wake a suspended or parked app manually, without waiting for someone to open it.
Uninstalling
Uninstalling removes the running app’s pods, revokes its OAuth client, and deletes its consent grants. The app’s entry in your tenant’s registry is untouched, so you can install it again later, and reviewing consent starts over from scratch. This can’t be undone.Related
Manage the app registry
Where a pushed image lands before it can be installed.
Use an installed app
Opening an app, what waking looks like, and what the errors mean.
Check an installed app
From the same app directory, rundip app status --json. This reads the saved app’s current
installation without reinstalling, changing its version or changing consent. It reports the exact
installation state and returns app_url only when ready is true. Readiness does not verify the
app’s queries, charts or what another viewer can access. Open it in a signed-in browser for those
checks; an unauthenticated request to the app URL is not a health check.
Readable app addresses
On data planes with readable addresses enabled, a successful installation publishes an address such ashttps://revenue-dashboard--altimate.apps.adp.example.com. Existing installations receive
one on their next successful installation retry or version change. Publishing a version alone does
not move an existing installation. To retry from the app’s directory,
run dip app install and follow its confirmation flow. Keep the same published version to preserve
the installed artifact. dip app status --json observes the result; it does not initiate this change.
Copy the returned app_url when ready is true. The assigned address stays fixed when display
names change, and earlier installation-ID links continue to reach the same installation.
If this retry fails, the installation reports Install failed and retains its previously published
address. The existing app may still serve there. Inspect the error and retry the installed version
after resolving its cause; the failed retry does not confirm that the readable address is ready.