App configuration

Two files control how your AppKit app starts and what it connects to: app.yaml (runtime behavior and environment variables) and databricks.yml (Databricks resources). Each app gets a fixed URL assigned at creation. It cannot change.

Building with Python?

AppKit targets TypeScript on Node.js. Python app development is not covered on this site. See the Databricks Apps docs for Python frameworks (Gradio, Streamlit, Dash).

Configuration files

app.yaml controls runtime behavior (startup command and environment variables):

command: ["npm", "run", "start"]
env:
  - name: LAKEBASE_ENDPOINT
    valueFrom: postgres
  - name: WAREHOUSE_ID
    valueFrom: sql-warehouse

The command is a sequence (array), not a shell string. Environment variable expansion is not supported in command except for DATABRICKS_APP_PORT.

databricks.yml declares Databricks resources, variables, and deployment targets:

resources:
  apps:
    my-app:
      resources:
        - name: postgres
          postgres:
            branch: ${var.postgres_branch}
            database: ${var.postgres_database}
            permission: CAN_CONNECT_AND_CREATE

Variables like ${var.postgres_branch} are resolved from the variables section of databricks.yml or from CLI flags at deploy time.

For the full AppKit-specific app.yaml reference including plugin resource bindings, see AppKit configuration.

Plugin manifest

Each AppKit app has an appkit.plugins.json that declares which plugins are active and what Databricks resources they require. This file is auto-generated by running:

npx @databricks/appkit plugin sync --write

This runs automatically during npm run dev and npm run build. Commit it alongside your code. The CLI and deployment pipeline use it to provision resources.

Resources

Apps access Databricks services through declared resources. Each resource has a name in databricks.yml. Use that name as the valueFrom value in app.yaml.

AppKit templates use conventional names for plugin-managed resources:

Resource	Resource name	What it provides
Lakebase Postgres	postgres	PostgreSQL connection
SQL Warehouse	sql-warehouse	SQL query execution
Model Serving	serving-endpoint	AI model inference
Genie space	genie-space	Natural language data queries
Job	job	Scheduled or triggered job
UC Volumes	volume	File storage

Additional resource types (Unity Catalog tables, connections, vector search indexes, MLflow experiments, and others) are listed in the official resources documentation.

Secrets

Neither config file contains the secret value. databricks.yml declares a resource pointing to a secret scope and key that you define, and app.yaml references that resource by name. The platform injects the decrypted value at runtime.

1. Store the secret value using the Databricks CLI:

   databricks secrets create-scope my-app-secrets
   databricks secrets put-secret my-app-secrets MY_SECRET --string-value "..."

2. Declare the secret resource in databricks.yml:

   resources:
     apps:
       my-app:
         resources:
           - name: my-secret # label for this resource (user-defined)
             secret:
               scope: my-app-secrets # Databricks secret scope name
               key: MY_SECRET # key within that scope
               permission: READ

3. Bind it to an environment variable in app.yaml:

   env:
     - name: MY_SECRET
       valueFrom: my-secret # references the resource name above, not the secret value

At runtime, MY_SECRET contains the decrypted secret value. Neither file contains the value itself.

Environment variables

The platform injects these variables automatically at runtime:

Variable	Description
DATABRICKS_HOST	Workspace URL
DATABRICKS_APP_PORT	Port your app must listen on
DATABRICKS_APP_NAME	App name
DATABRICKS_CLIENT_ID	Service principal client ID
DATABRICKS_CLIENT_SECRET	Service principal client secret
DATABRICKS_WORKSPACE_ID	Workspace ID

Custom variables go in app.yaml under env. Use value for plain text, valueFrom for resource names. Never put secrets in value.

Auth model

Each app gets a dedicated service principal. Databricks injects DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET automatically at runtime and deletes the service principal when the app is deleted.

User authorization (Public Preview) forwards the signed-in user's token through the x-forwarded-access-token HTTP header. Scopes (for example, sql, dashboards.genie, files.files) are configured in the workspace UI. AppKit's built-in Genie and Model Serving plugins use this automatically. See execution context for the AppKit implementation, or app authorization for the full platform details.

Compute

Size	vCPU	RAM	DBU
Medium	Up to 2	6 GB	0.5
Large	Up to 4	12 GB	1.0

Medium is the default. Compute size is configured in the workspace UI (not available through the CLI).

Constraints

• No durable filesystem (use Lakebase Postgres, DBSQL, or UC Volumes for persistence)
• Files larger than 10 MB fail deployment
• SIGTERM gives 15 seconds before SIGKILL
• Runtime: Ubuntu 22.04, Node 22, Python 3.11

See Best practices for guidelines on shutdown handling, secrets hygiene, and networking.

App statuses

Status	Meaning
Running	App is healthy and serving traffic
Deploying	New deployment is in progress
Crashed	App failed to start or exited
Stopped	App was manually stopped

Where to next

See Apps development for local setup, deploy flags, and the full plugin API, or browse the templates catalog for complete patterns.