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.
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.json and fails if they drift.
  • A Claude Code skill for authoring this specific app, unless you pass --no-skill.
Skip the scaffold entirely and start from a worked example instead: the SDK ships a complete, runnable Streamlit app and a complete, runnable single-page app you can build on directly.
For TypeScript and single-page apps, run 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:
The Python scaffold includes 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.
Browser JavaScript in every installed app queries through /.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. The frontend scaffold’s header already does.
  • Signed in as <email>, from the caller’s identity: ctx.user.email in a single-page app, user.email from user_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 raise PermissionDeniedError 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 embedded data: 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. After the preview shows the intended answer, publish and install from your app directory:
Review the selected version, requested data access and code-trust message, then confirm the install. 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 with viewer, 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 reports repository 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
This is the fast loop: it runs your app on your laptop and gets real rows back, using nothing but your own 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:
If your configuration does not already define 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. SQL DECIMAL 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 skips dip 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.
To use it, create a service user and an 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:
This path dials the engine directly, with nothing else in between, which is different from 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
This refuses to let you ship an app that:
  • 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.
See Build and push an image for what comes after a clean check.

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.