dip app new scaffolds a data app: a starter project already wired to read the calling user’s identity
and query your engine as them. From there you can run it locally against real data, and check it before
you ship it.
Agent-built apps include a short first-visit walkthrough explaining the app’s views, data
and actions. Viewers can turn it off with Show walkthrough in the app’s settings and
reopen it with Replay walkthrough. Ask your agent to report its visual inspection of
each step before publishing. Saved preferences are a convenience for that viewer in that
browser; they are not shared or durable.
Scaffold an app
Choose Python, Streamlit or TypeScript when the app uses certified metrics: those runtimes can query the semantic layer. Choose Frontend (SPA) for a browser app that only runs SQL; its SDK has no semantic layer API.- Python
- TypeScript
- Streamlit
- Frontend (SPA)
Scaffold a Python app
--name becomes the app’s id: kebab-case, and it seeds the app’s hostname, so keep it short. --out
defaults to ./<name>, and the scaffold never overwrites an existing file: it names every collision
instead. See the full flag reference.
Replace probe_shop with the catalog your app reads. --catalog writes that name into the manifest’s
read capability and consent reason for all four runtimes. To find the name, run SHOW CATALOGS in
the SQL editor or ask your agent to use MCP browse with level: "catalogs" on the chosen engine.
Use the returned SQL catalog name; an integration’s display name can differ.
Workspace databases must be named: *
does not include them, even when you own the database. Without --catalog, the scaffold keeps *
for ordinary catalogs you can read, including Trino’s system catalog, but not workspace databases.
The consent reason names this scope. The scaffold does not discover or choose a catalog for you.
For long names, it shortens the name in the consent prose to fit the 200-character limit; the
capability always declares the full catalog name.
What you get:
- Your app’s code, already wired to read the calling user’s identity and query the engine as them.
- The Altimate SDK vendored into your repo: you do not need to download a separately published
SDK package. TypeScript and single-page apps install build dependencies with
npm install. - A starter manifest declaring one read capability for the selected catalog, or
*when you omit--catalog. This grants nothing by itself; the person using the app must also have access to the data. Narrow the capability to the catalogs, schemas and tables your app actually reads before you ship it. See Write the app manifest. - A Dockerfile, ready for
dip app build. - A conformance test that runs your manifest against the committed
manifest.jsonand fails if they drift. - A Claude Code skill for authoring this specific app, unless you pass
--no-skill.
npm install in your app directory before running checks or
starting local development. This also builds the bundled SDK. Its own test runner is not included;
your app’s conformance check runs with npm test.
For Python and Streamlit, create and activate a virtual environment, then install the scaffold’s
requirements before running dip app check:
pyarrow, which .sql() and .query_metrics() need for Arrow results.
Streamlit installs it and pandas through its own dependencies; add pandas to a plain Python app
if you use .sql_df().
For chart labels, pass a frame through readable_columns(df) (invoice_date__month reads as
“Invoice date (month)”). For certified metrics, call query_metrics_df(..., readable=True) or pass the
compile response’s metric_columns as the second argument, so a metric reads by its own name. The Streamlit scaffold
charts a result’s numeric columns against its first non-numeric column with those labels. It builds the
frame with chart_frame(data.sql_rows(sql)), which converts columns by their engine type, because Trino
sends DECIMAL values (most money columns) as strings.
Reading who’s calling
Every request your app receives while it’s running carries the identity of the person who made it, and you never see a shared service identity. Each SDK exposes it as a small context object built from that request./.altimate/engine on the app’s own
Dippr origin. Dippr adds the engine credential server-side; the page never receives an engine token.
Requests to POST /.altimate/token are refused. Use createBrowserDataClient for browser queries.
Tell each viewer whose view it is
A colleague who opens your link needs to know the page shows their own data. Show three things near the top. Thefrontend scaffold’s header already does.
Signed in as <email>, from the caller’s identity:ctx.user.emailin a single-page app,user.emailfromuser_context()in Streamlit. Leave the line out when the email is empty; a viewer with no email on record has none.You see only the rows your access allows.Show it to everyone. It is true for every viewer because every row on the page comes from a query run as them. Keep it true: an app with a server must not cache one viewer’s result and show it to another. Do not show or hide it based on how many rows came back.Data as of <time>, the time the query finished. Set it when the result arrives.
Show an access message when a query is refused
The Python and TypeScript SDKs raisePermissionDeniedError when the engine returns
PERMISSION_DENIED. Its message is ready to show as plain text:
You don’t have access to this data — ask the app’s owner.
For recognized table refusals, the SDK names the table only after confirming that the same viewer
can currently list it. Hidden tables and unavailable visibility checks keep this data. A current
owner display name replaces the app’s owner when available. Email addresses are never used as
the contact name. Human owners currently have no separate display name, so their apps use the
generic owner wording.
The generated Python, Streamlit, TypeScript and single-page apps display this message. When customizing
an app, show the exception’s message as plain text, and keep other query failures separate. Do not
retry a permission refusal or replace the viewer’s identity with the owner’s credentials.
The message applies to Python sql_rows, sql and sql_df, and TypeScript data.sql. Successful
queries keep their usual result shape. Existing apps need to update their bundled SDK and republish
to use this handling.
When the platform briefly refuses to refresh your token
A TypeScript app’s server-side code that builds its engine client from the request gets its engine token from the platform on each call. This token stays on the server. The platform answers that request in one of two ways, and the SDK treats them differently.
If every attempt is refused, the call fails with a plain
Error whose message starts with
altimate: token endpoint answered and names the last status and “a transient refusal”. That error is
not SessionExpiredError, so do not ask the user to sign in again. Any other error from a query, such
as EngineError for invalid SQL, PermissionDeniedError for refused access, or QueryAbortedError for a cancelled
request, is not a token problem: handle it as you would any query failure and do not retry it blindly.
Telling a lost session from other failures
Which engine kind you’re talking to
Your app speaks whatever query engine it’s pinned to, in that engine’s own protocol (today, always Trino). The SDK reads which engine kind it’s pinned to from the platform-injected environment and refuses at construction, with a clear message, if it doesn’t recognize the kind, rather than sending Trino-shaped queries at something that isn’t Trino.What can an app page load or call?
An installed app page’s fetches and subresource requests are confined to its own Dippr app origin, with the embedded image and font exceptions below. This applies to every installed app, including pages served by Python, TypeScript and Streamlit apps. Bundle your JavaScript, styles, fonts, images and other assets with your app. Calls to external APIs and assets hosted on CDNs are blocked. Inline JavaScript is blocked, so load scripts from bundled files; inline styles are allowed. Images and fonts can also use embeddeddata: URLs.
App pages cannot submit browser forms, embed other frames or start web workers. The console’s
embedded viewer also blocks app-created popups and allows file downloads, including export buttons.
It keeps the app’s frame on Dippr app addresses: a link or script that sends the frame to another
site is blocked, so open external pages from outside the app.
In a current browser, an installed static app is shown only in that viewer: a browser tab
that asks for one of its pages directly is sent to the viewer, so don’t build a static app that
depends on being the top-level page. dip app dev still previews it in a tab of its own.
These restrictions apply even when your app supplies
its own Content-Security-Policy. Dippr removes app-supplied reporting headers and early hints, so an
app cannot use them to send browser reports or preload external assets.
WebRTC is blocked only in browsers that enforce the webrtc 'block' Content-Security-Policy
directive. An app that runs its own server, opened at its own address outside the console, can
still navigate itself to an external URL carrying data. These restrictions
are not a complete outbound-data boundary. Install only app code you trust.
What your app’s health path must do
If your component declares a health check path (or accepts the default), it has to answer with a successful response without reaching the engine at all. Your app should be able to render before anyone has queried anything through it.From preview to a shareable link
After the preview shows the intended answer, publish and install from your app directory:dip uses your own login and waits for a ready app before printing its link. Send that link to your
colleague; their queries use their own access. No administrator needs to install your own app for you
when your role allows it. Docker and buildx are required to publish from this computer.
The install follows the exact publication from this directory. It uses the registry’s plane and a
compatible engine from your preview, or the sole compatible engine. If a choice is needed, it names
the available engines so you can pass --engine NAME. See Install an app.
Publishing your own apps
Members withviewer, including analyst, can publish and install their own apps by default.
Your app’s data capabilities must be read-only when you use these own-app permissions.
An author with broad publishing permission can also publish writable apps.
An administrator can turn off Publish own apps or Manage own apps for a role in
Settings → Roles & permissions. Preview is a separate permission. Turning off own-app
management also prevents parking or uninstalling your app; an app administrator can still manage it.
See Own-app role settings.
From Claude or ChatGPT on the web, your AI publishes a read-only app for you with the MCP
app_publish tool: it takes one HTML page and the
queries it runs, and installs the app as you. It publishes only static, read-only apps, whatever
your role, and uses the same own-app permissions.
App code is trusted, like spreadsheet macros. Each query uses the current viewer’s grants within
the installed ceiling, but a trusted app server can retain or redistribute rows it has received.
Browser restrictions do not make untrusted app code safe.
Publishing without replacing another author’s images
Choose an app ID and component image repositories that you own. Your first upload reserves a new app name; another publisher cannot use permission to create apps to replace your app or its component images. Explicit component image references receive the same protection, including references kept by older published versions. If a push reportsrepository ownership refused, ask the owner or an administrator, or change both
your app ID and any component repository that belongs to someone else. Increasing the version or
signing in again does not give you permission to replace those images. See
Who owns a pushed app?.
Environment rules
Your component can declare its own environment variables in the manifest, but three names are reserved for the platform and always win over anything you declare:PORT, HOME, and anything starting with
ALTIMATE_. Declaring one of those in your manifest is rejected outright.
Running it against your real engine
Run your app locally, against your own engine, as yourself
dip login session, no environment variables and no separate credential. It discovers your
query engines automatically and picks the first one it finds; name a different one with --engine <name>
when you have more than one. Members with viewer, including analyst, can preview an app they
are building locally. You do not need permission to publish or install an app.
For a custom role, ask your role administrator to allow both Data apps → Preview own apps and
Query engines → Read. Preview permission alone does not let dip app dev discover an engine,
even when you name one with --engine. The roles matrix shows Preview also needs Query engines:
read when preview is allowed but engine read is missing. Inheriting viewer includes both
permissions.
Preview queries use the intersection of your own data grants and the app’s declared capabilities.
Your row filters and column masks still apply. The viewer role has no seeded table data grants,
but you may have SELECT on your personal workspace database or other granted data. Preview shows
exactly what your grants allow within the app’s declared capabilities; it grants no extra data access.
Only you can obtain query credentials for your local preview or delete its sandbox; another member
cannot use it as you.
When your manifest declares a data capability, dip app dev waits briefly before your app starts for
the data plane to pick up your app’s ceiling. If that takes longer than the wait, it says the ceiling is
still propagating: until it arrives, usually within a few seconds, a query your ceiling allows can
still be refused with PERMISSION_DENIED. Run it again once the ceiling has propagated. “Active” means
the ceiling is being enforced, not that every query will succeed. See
dip app dev.
The TypeScript starter displays Local dev: querying as you in its local responses, including query
errors. When you open an installed app, it displays the signed-in user’s email instead.
A single-page app has no server component to hold a token, so for that runtime dip app dev also runs
a small local stand-in that handles engine requests the same way the installed app will, so your app
behaves the same locally as it will once installed, without your browser ever holding an engine
credential. The local browser endpoint also refuses POST /.altimate/token; use
createBrowserDataClient for queries. Python and TypeScript server code can still refresh credentials
through their separate server-side endpoint.
The single-page app starter also applies the installed browser policy during local development: external
API calls, CDN assets and arbitrary inline scripts are blocked. Vite’s React hot reload has one
script exception: a hash allows only its exact refresh preamble. Its WebSocket stays on the app’s
own origin. Local pages allow embedding only by their own origin; installed pages also allow your
tenant’s console origin. Referrers, content sniffing and DNS prefetching are disabled in both.
dip app dev looks for the expected browser policy setting in your Vite configuration text. If it
cannot find it, it prints a warning and continues starting your app. This is a best-effort hint:
matching text in a comment or elsewhere in the configuration can suppress the warning even when
your local pages have no browser policy. Add this line inside server in vite.config.ts:
devBrowserHeaders, generate a fresh single-page app
starter in a separate directory and copy its browser-policy imports, constants and helper into your
configuration. Keep the exact React refresh preamble hash; do not allow arbitrary inline scripts.
The local check helps you test how your app will behave once installed. It reads the configuration;
it does not inspect served pages or restrict your Node process. Python, TypeScript server and
Streamlit dev servers manage their own response headers. Installed apps of every runtime always
enforce the browser policy, regardless of your local configuration.
dip app dev needs a dip login session; there’s no API-key path for this command.Exact integers in JavaScript results
The TypeScript SDK returns integer JSON literals outside JavaScript’s safe integer range as decimal strings, including inside arrays and maps. Safe integers remain numbers. SQLDECIMAL values remain strings;
floating-point values remain numbers, and SQL null remains null.
Display exact integer strings directly. For integer arithmetic or numeric sorting, convert them with
BigInt(value); converting them to Number can lose digits. JSON serialization preserves the strings.
If you convert a value to bigint in your app, convert it back to a string before JSON serialization.
A second, lower-level way to run your query code
The SDK also offers a constructor that skipsdip app dev entirely and exchanges an API key for an
engine token directly, useful for a small local entrypoint that exercises your query code outside your
Streamlit or HTTP handlers.
alt_ API key under Settings → Service users, grant it
whichever roles you want the preview to reflect, and copy your engine’s connect URL from the console:
dip app dev. It’s local-development-only: a deployed app never holds a standing key like this, and
you should delete the service user once you’re done testing with it.
Checking your app before you ship it
The single-page starter displays query columns in their SQL order, including repeated column names. When you customize its result table, identify columns by position so each header stays aligned with its value when you run a different query. Use SQL aliases when you want distinct labels.Conformance check
- Has an invalid manifest.
- Has drifted between your manifest source and the committed
manifest.json. - Imports a raw database driver (Trino, Postgres, Snowflake, DuckDB, and so on) directly: a second, ungoverned door into data is exactly what the platform exists to remove.
Related
Write the app manifest
Every field your manifest can declare, and what gets rejected at registration.
Build and push an image
Build your app’s image and ship it to your tenant’s registry.