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.
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: ["pnpm", "run", "start"]
env:
- name: LAKEBASE_ENDPOINT
valueFrom: postgres
- name: DATABRICKS_WAREHOUSE_ID
valueFrom: sql-warehouseThe command is a sequence (array), not a shell string. Environment variable expansion is not supported in command except for DATABRICKS_APP_PORT.
The default AppKit template uses pnpm. Apps that use pnpm must set command; only npm apps fall back to npm run start without one. In a pnpm workspace, commands that run pnpm recursively must call corepack pnpm. See Manage dependencies.
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_CREATEVariables 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 generated by the template's sync script, which runs appkit plugin sync --write:
pnpm run syncThis runs automatically before the template's dev and build scripts. Commit it alongside your code. databricks apps init prompts for each plugin's resources from the template's manifest, and databricks apps validate (which databricks apps deploy runs first in a project directory, unless you pass --skip-validation) uses it to check that resources accessed on behalf of the user are allowed and that their scopes are in user_api_scopes. The resources themselves are declared in databricks.yml.
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 |
| AI Gateway model service | model | Model service calls through AI Gateway |
| Model Serving endpoint | agents-serving-endpoint | AI model inference for the agents plugin (the deprecated serving plugin uses serving-endpoint) |
| Genie Agent | genie-space | Natural language data queries |
| Job | job | Scheduled or triggered job |
| UC Volumes | files | File storage |
AppKit plugins don't declare the model service, so apps init doesn't prompt for it: add it to databricks.yml yourself. model is the default key the Apps UI gives it.
Additional resource types (Unity Catalog tables, Unity Catalog connections, AI Gateway model services, AI Search indexes (formerly Vector Search), 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.
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 "..."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: READBind 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.
When you turn on app telemetry, the platform also sets OpenTelemetry variables such as OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME, and writes to Unity Catalog tables. Logs arrive automatically; traces and metrics need custom instrumentation.
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 forwards the signed-in user's token through the x-forwarded-access-token HTTP header, letting calls run on behalf of the user (OBO) rather than the app's service principal. Declare the scopes your app needs in user_api_scopes in databricks.yml (for example, sql, genie, model-serving, files); user authorization must also be enabled for the workspace. AppKit's built-in Genie routes and the agents plugin's plugin:<name> tools run as the signed-in user (OBO) by default. Declaring the matching scope (for example genie or sql) is what lets the forwarded token make the call; without it the request fails rather than falling back to the service principal (AppKit falls back only in local development). See execution context for the AppKit implementation, or app authorization for the full platform details.
The current scope names include sql, genie, model-serving, files, ai-gateway, vector-search, postgres, and apps; the older dotted forms (dashboards.genie, serving.serving-endpoints, files.files) are deprecated aliases you may still see in existing apps or tutorials.
Compute
Compute sizes are MEDIUM (the default), LARGE, and XLARGE (availability varies by workspace). Set the size in the workspace UI or with the --compute-size flag on databricks apps create and databricks apps update. See Configure compute resources for the vCPU, RAM, and DBU per size.
An app can also run on up to 5 instances behind one URL, for higher availability and concurrency, with at most 20 such apps per workspace. Turn on horizontal scaling in the app's settings in the workspace UI. The CLI also exposes --compute-min-instances and --compute-max-instances on databricks apps create and databricks apps update. See Horizontal scaling.
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.