Skip to main content
This quick start shows how to deploy a Superblocks app so it runs inside Databricks as a Databricks App using the official Superblocks template. This guide focuses on getting your app live quickly. For advanced configuration or implementation details, refer to the template repository README.

​
What You’ll need

Before you start, make sure you have:

​
Step 1: Create the Databricks App and add the secret

Create a new Databricks App in your workspace by following the official Databricks documentation:
Create a Databricks App During the app creation flow, add the Superblocks embed token as an App resource:
  1. In the Configure step, go to App resources
  2. Click Add resource
  3. Select Secret as the resource type
  4. Choose the secret scope and secret key where the Superblocks embed token is stored
  5. Grant the app read access to the secret
  6. Assign a resource key, for example superblocks_embed_token

​
Step 2: Clone the Databricks App template

Clone the official Superblocks Databricks App template: 
$ git clone https://github.com/superblocks-samples/superblocks-databricks-app
$ cd superblocks-databricks-app
$ npm install
$ npm run build
This template is a lightweight wrapper that embeds your Superblocks app and integrates authentication inside Databricks.

​
Step 3: Configure the app

Open app.yaml and configure the required values for your Databricks workspace and Superblocks app. At a minimum, configure:
  • Your Superblocks instance URL, for example https://app.superblocks.com
  • Your Superblocks application ID
  • A reference to the Databricks Secret resource key you created in Step 1
For example: 
env:
  - name: SUPERBLOCKS_URL
    value: https://app.superblocks.com
  - name: SUPERBLOCKS_APPLICATION_ID
    value: <your-superblocks-app-id>
  - name: SUPERBLOCKS_EMBED_ACCESS_TOKEN
    valueFrom: superblocks_embed_token
Do not hard-code secret values. Only reference the resource key.

​
Step 4: Deploy to Databricks

Sync the source code into your Databricks workspace and deploy your app 
$ databricks sync . /Workspace/Users/<your-email>/<your-app-name>
$ databricks apps deploy <your-app-name> \
  --source-code-path /Workspace/Users/<your-email>/<your-app-name>
Databricks builds and launches the app using the Superblocks template.

​
Step 5: Open the app

Once deployment completes, open your app at: https://<your-workspace>.cloud.databricks.com/apps/<your-app-name> Your Superblocks app is now running inside Databricks!

​
How it works

Once deployed, the Databricks App runs as a lightweight wrapper around your Superblocks application. At a high level:
  • Users access the app directly inside Databricks and authenticate with their Databricks identity
  • The app embeds the Superblocks UI and passes user context securely to Superblocks
  • Backend APIs generated by Clark execute through the Superblocks data plane
  • Those APIs issue SQL queries and Databricks REST API calls directly to Databricks services
  • Databricks executes all data, job, pipeline, and AI workloads
  • Unity Catalog enforces permissions for every query and API call
Clark builds the APIs. Databricks execute the workloads. This model keeps application development fast while ensuring data access, execution, and governance remain fully Databricks-native.

​
Learn more about the deployment

This quick start intentionally keeps deployment simple. If you want to learn more about:
  • How the Databricks App wrapper works
  • Authentication and token exchange flows
  • Advanced configuration options
  • Customizing the wrapper app
Refer to the full template repository and README: Superblocks Databricks App Template