Data Apps - AI Assistant Quickstart

A Data App is built by asking or with code. This page covers building one in your own project with the Astrato CLI, for Astrato-managed hosting. To build without code, use App Builder. An external AI agent can also control an open App Builder project through MCP; see External agents using App Builder.

If you prefer to build visually in Astrato, create a Workbook instead. See Astrato terminology for a quick comparison.

Preview: on deployments with publications enabled, use the CLI to build and publish a local project, or use the Private Preview Nash App Builder to publish a saved app. MCP Freeform tools can create an unpublished target and manage it; they do not upload or publish content. See hosted app sessions. Private preview and release history are not available.

If you will deploy the app yourself, use the externally hosted app quickstart instead. That route does not use the Astrato CLI or @astrato-io/app-runtime.

External AI agents and local development

For projects developed with an external AI agent or your own development tools. You manage the frontend files, package installation and build commands in your development environment. The Astrato CLI connects the local app to Astrato through the App runtime during development and publishes the built app to Astrato hosting. It does not emulate Astrato services. Follow the steps below for CLI setup, authentication, preview and publishing.

External AI agents fetch current documentation with their own tools; see the agent workflow guide. For MCP control of a Builder project, follow External agents using App Builder.

What you need

• Node.js 24, version 24.18.0 or later. Node 25 is not supported by the current CLI package.
• @astrato-io/cli, @astrato-io/app-runtime and any other Astrato packages used by the page. Follow the installation instructions.
• An existing Vite frontend project with working dev and build scripts. astrato init adopts a project; it does not scaffold one.
• Access to a semantic layer available to Astrato’s query engine.

1. Install the CLI

Package versions

Before package-based development, inspect the project’s declared dependencies and lockfile, then check the configured registry for newer releases. Reuse the results within the task. Include the Astrato CLI when the workflow uses it, and apply the same check to externally hosted apps.

For a new project or a dependency addition, use the newest compatible release allowed by the project’s dependency policy. For an existing app, check release notes, peer dependencies and runtime requirements before upgrading; a newer release is not automatically compatible. Respect explicit version requests and release-age restrictions. Record any reason to retain an older release, and report registry access failures instead of claiming the versions are current. Verify changed integrations using the installed package’s references and live behavior.

Check whether the global command is already available:

astrato --version

If the command is missing, install it globally:

npm install --global @astrato-io/cli
astrato --version

For npm installation failures, review the installation instructions. Completing astrato login does not configure npm access.

If astrato --version reports that the command is not found, npm’s global folder is not on your PATH environment variable. Add it, then open a new terminal. The installation instructions give the steps for Windows and macOS or Linux.

List the complete command surface from the installed version rather than relying on memory:

astrato --help
astrato help init
astrato help dev

astrato help <command> and astrato <command> --help are equivalent.

2. Authenticate this computer

Check authentication before starting local runtime access:

astrato status

For machine-readable output in automation or an AI-agent workflow, use:

astrato status --json

If the status says you are not authenticated, run:

astrato login

The CLI opens an Astrato device-authorization page and prints a URL and user code. Complete the approval in your browser using the Astrato account you want the CLI to use. The CLI stores the resulting login in the operating system credential store; it does not write credentials into the project.

After approval, verify it:

astrato status

For machine-readable output, use:

astrato status --json

Authentication checkpoint for AI agents

An AI agent should run astrato status --json. If the CLI is unauthenticated, it must pause the work that needs Astrato access and tell the user exactly this:

Please run astrato login in your terminal and complete the browser approval yourself. Tell me when it finishes, and I will re-check astrato status --json.

The agent must not run or automate astrato login, ask for the device code, request a PAT, token or cookie, inspect the credential store, or replace the Data App workflow with a custom proxy. It should resume only after the user confirms completion and status reports authenticated.

3. Scaffold the frontend

Use any supported frontend setup with Vite scripts. For example:

npm create vite@latest my-astrato-app -- --template vanilla-ts
cd my-astrato-app
npm install
npm install @astrato-io/app-runtime @astrato-io/visualizations

Do not install @astrato-io/app-runtime in an externally hosted app.

4. Configure the semantic layer

Run init in the project directory or pass its path explicitly:

astrato init . --semantic-layer-id <semantic-layer-id>

Select an existing semantic layer and use its returned ID; never invent one. You can find accessible layers through the Nash MCP gateway. The ID is required; an interactive astrato init . prompts for it if omitted.

init creates or validates astrato.json, detects conventional Vite scripts and adds .astrato/ to .gitignore. It works without login and creates nothing in Astrato. See the CLI reference for non-interactive options and the complete configuration contract.

Validate the project:

astrato validate .

For machine-readable output:

astrato validate . --json

5. Use the Data App runtime

Authored browser code asks the hosting boundary for its context. Do not configure a PAT, tenant ID, semantic-layer ID, datasource type or Astrato API URL in source code.

import { createAstratoApp } from '@astrato-io/app-runtime';

async function start(): Promise<void> {
  const app = await createAstratoApp();

  const getFieldMetadata = app.client.services.engine.fields.getFieldMetadata;
  if (!getFieldMetadata) {
    throw new Error('Astrato field metadata is unavailable.');
  }

  const fieldMetadata = await getFieldMetadata({
    datasourceType: app.dataBinding.datasourceType,
    semanticLayerId: app.dataBinding.semanticLayerId,
  });

  console.log(fieldMetadata);
}

start().catch((error) => console.error(error));

Use app.client wherever SDK documentation refers to an authenticated client, and use app.dataBinding when creating a standalone visualization instance. The Data App runtime reference documents the complete returned object and errors. Call app.destroy() only when the browser application is permanently torn down.

6. Run through the CLI-owned origin

astrato dev .

The CLI prints and opens an HTTP sign-in URL that establishes a browser session and takes you to the clean astrato-....localhost App origin. Do not open the raw Vite URL: only the CLI-owned origin provides the Data App runtime bootstrap, browser session and guarded Astrato routes. Vite hot reload continues to work through that origin. Press Ctrl+C to stop both the gateway and the supervised frontend process.

To prevent dev from opening a browser automatically, use:

astrato dev /absolute/path/to/project --no-open

Open the printed sign-in URL in a browser on the same computer. Reuse that same link whenever you need it, including in a different browser profile. It stays valid until this dev process stops; it has no short expiry and is not consumed by opening it. Stopping the process invalidates the link and its browser sessions. After restarting, use the new sign-in URL.

The link grants access to this running local app; it does not contain your Astrato OAuth token or a PAT. Avoid sharing it: anyone with the link who can reach the local gateway can use it while the process runs. Remote browsing and port forwarding are not supported. dev is long-running and does not support --json.

The app queries the model currently available to Astrato’s query engine. After changing that model, reload the page to refresh its field metadata. The CLI does not pin a revision or send model-change notifications; an open page can have older metadata than subsequent queries.

Browser automation

For AI-assisted workflows, prefer a built-in or agent-owned browser on the same computer when it supports the local app, unless you requested another browser. Use --no-open when you or the tool will open the printed HTTP sign-in URL in that browser. Without it, the CLI opens your default browser; the same link still works in the agent’s browser.

Open the sign-in URL in each browser profile you intend to use. Once connected, use the clean app URL for subsequent navigation. Another tab in the same profile shares the session. A separate profile or a browser with cleared cookies can reconnect through the original sign-in URL without restarting the app. Opening the clean app URL alone, or fetching a link in a different tool, does not establish that browser’s session. Do not copy cookies between browsers.

An agent may pass the CLI’s printed sign-in URL to its browser tool. This local admission link is separate from Astrato account authentication; the agent must still follow the authentication checkpoint. Reconnecting a browser does not require account login or terminal input. After dev restarts, use the newly printed link.

If the browser tool cannot reach the local app, use a browser you agree to have the agent control, or check the app yourself. An agent without a compatible browser tool should provide manual checks for chart rendering and interactions, and clearly distinguish your results from its own verification.

7. Build the static artifact

astrato build .

The CLI runs the configured package-manager build script, validates the static output and writes a deterministic .astrato/build-manifest.v1.json. Building requires valid local configuration but not authentication, and it does not upload or deploy anything.

For machine-readable output:

astrato build /absolute/path/to/project --json

8. Publish and manage the app

For local projects, read the CLI publication workflow for authorization, exact commands and interrupted-upload recovery. Create an unpublished target, read its ID and version, then publish the project to that explicit target. The semantic layer must already be published and its data connection must use a supported exit node. Use the current hosted App runtime contract.

Publishing verifies the uploaded HTML, JavaScript and other assets before replacing current content. Open Apps in the lobby to open apps, edit names and labels, manage access, unpublish or delete. See Manage data apps for permissions and retention behavior. A successful build alone does not prove a hosted app or its queries work.

Hosted apps negotiate Brotli or gzip compression for text assets of at least 1 KiB, including HTML, JavaScript, CSS, JSON and SVG. Browsers that do not request compression receive the original representation. Assets remain private and revalidate on reuse. File access uses a short-lived publication session; see publication access for its expiry behavior.

Continue with the Visualizations reference to render a governed chart, the Interactivity guide to link charts, or the Semantic layer workflows when the model itself needs to change.