Development
App development
This page is the CLI and workflow reference for Databricks Apps and AppKit. It covers adding plugins, scaffolding, deploying, managing, and troubleshooting your app.
Local setup
Copy .env.example to .env and fill in your workspace URL and resource IDs before running npm run dev. AppKit reads these for local connections to Databricks resources.
Example .env for an app with Lakebase Postgres:
DATABRICKS_HOST=https://<workspace>.cloud.databricks.com
LAKEBASE_ENDPOINT=projects/<project>/branches/production/endpoints/primary
If your app uses Lakebase, also grant your local user the databricks_superuser role before running locally. The app's service principal creates schemas and tables on first deploy and owns them. Without this grant, your local identity cannot access those objects:
GRANT databricks_superuser TO "<your-email>";
See Lakebase Development for the full local access workflow.
For testing against production data without redeploying, see the remote bridge.
Add a plugin
To add a plugin to an existing app, import and register it in createApp in server/server.ts:
import { createApp, server, lakebase, genie } from "@databricks/appkit";
const AppKit = await createApp({
plugins: [server(), lakebase(), genie()],
});
Then regenerate appkit.plugins.json with the updated resource requirements:
npx @databricks/appkit plugin sync --write
This runs automatically during npm run dev and npm run build. Commit the updated appkit.plugins.json alongside your code. It tells the deployment pipeline which resources to provision.
See the AppKit plugins reference for configuration options for each plugin, or Creating custom plugins to add your own.
Discover plugins
List available plugins and their required resource fields:
databricks apps manifest
Options
Scaffold options
Use databricks apps init to scaffold a new AppKit project. The Apps Quickstart shows the fast path. Use these options for non-interactive or advanced scaffolding.
databricks apps init --name my-app
Options
Passing --name suppresses prompts and uses defaults for unspecified options. App names must be lowercase, hyphenated, and 26 characters or fewer. Run databricks apps manifest to see available plugins and their --set keys.
Environment configuration
Local (npm run dev): variables from .env in the project root.
Deployed: variables from app.yaml env entries. Use value for plain strings and valueFrom for resource bindings:
env:
- name: LAKEBASE_ENDPOINT
valueFrom: postgres
- name: WAREHOUSE_ID
valueFrom: sql-warehouse
- name: APP_LOG_LEVEL
value: info
Resources referenced by valueFrom must be declared in databricks.yml. See App configuration for the full resource list.
Pre-deploy checklist
Before deploying to production:
- App binds to
0.0.0.0onDATABRICKS_APP_PORT app.yamlcommand uses array syntax (no shell strings)- No files larger than 10 MB in the project
- Secrets use
valueFrom(nevervalue) databricks.ymldeclares all required resourcesdatabricks apps validatesucceeds (--skip-testsskips tests for a faster run)npm run buildsucceeds locally
Validate
Run validation from your app project directory before deploying:
databricks apps validate --profile $DATABRICKS_PROFILE
Validation runs a build, typecheck, and lint. Pass --skip-tests for a faster run.
Deploy
databricks apps deploy
Options
The CLI validates configuration, builds the project, uploads it, and starts the app. By default it runs the same project validation as databricks apps validate (build, typecheck, lint). Pass --skip-validation to skip that step. No --source-code-path is needed when deploying from a scaffolded AppKit project.
Verify the deployment
Check that the app deployed successfully:
databricks apps get my-app -o json
Options
Example output
{
"name": "my-app",
"url": "https://my-app-1234567890.us-west-2.databricksapps.com",
"description": "A Databricks App powered by AppKit",
"compute_size": "MEDIUM",
"app_status": {
"message": "App has status: App is running",
"state": "RUNNING"
},
"compute_status": {
"message": "App compute is running.",
"state": "ACTIVE"
},
"active_deployment": {
"deployment_id": "a1b2c3d4e5f6",
"source_code_path": "/Workspace/Users/you@example.com/.bundle/my-app/default/files",
"status": {
"message": "App started successfully",
"state": "SUCCEEDED"
}
},
"resources": [
{
"name": "postgres",
"postgres": {
"branch": "projects/my-project/branches/production",
"database": "projects/my-project/branches/production/databases/db-abc123",
"permission": "CAN_CONNECT_AND_CREATE"
}
}
],
"service_principal_client_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
View logs:
databricks apps logs my-app
Options
Example log output
[SYSTEM] [INFO] Starting Databricks Apps runtime...
[SYSTEM] [INFO] Starting deployment a1b2c3d4e5f6...
[SYSTEM] [INFO] Downloading source code from /Workspace/Users/.../src/a1b2c3d4e5f6
[SYSTEM] [INFO] Installing dependencies...
[BUILD] added 899 packages, and audited 900 packages in 21s
[SYSTEM] [INFO] Dependencies installed successfully.
[SYSTEM] [INFO] Running build script npm run build:server && npm run build:client
[BUILD] ✔ Build complete in 30ms
[BUILD] ✓ built in 2.80s
[SYSTEM] [INFO] Build completed successfully.
[SYSTEM] [INFO] Starting app with command: [npm run start]
[APP] [appkit:lakebase] Lakebase pool initialized
[APP] [appkit:server] Server running on http://0.0.0.0:8000
[APP] [appkit:server] Mode: production (static)
Managing apps
databricks apps stop my-app
databricks apps start my-app
databricks apps delete my-app
Options
apps delete prompts for confirmation. Pass --auto-approve in CI to skip the prompt.
CI/CD
For automated deploys in CI, set DATABRICKS_HOST and DATABRICKS_TOKEN (or use OAuth with DATABRICKS_CLIENT_ID and DATABRICKS_CLIENT_SECRET):
DATABRICKS_HOST=https://<workspace>.cloud.databricks.com \
DATABRICKS_TOKEN=dapi... \
databricks apps deploy
Or use a pre-configured profile:
databricks apps deploy --profile ci-profile
See the Databricks CLI authentication docs for all auth methods.
Troubleshooting
For additional troubleshooting, see Deploy apps and the AppKit remote bridge for local connection issues.
- App fails to deploy: Check logs for error messages, validate
app.yamlsyntax, and verify that secrets and environment variables in theenvsection resolve properly. Confirm all dependencies are included or installed. - 401 errors (authentication): Verify your token is valid (
databricks auth token --profile <PROFILE>), hasn't expired, and includes the required OAuth scopes. Your token's scopes must be a superset of the scopes configured for the app's user authorization. - 403 errors (permission denied): Verify you have
CAN USEpermission on the app. Insufficient OAuth scopes can also cause 403s even with valid permissions. - 404 errors (app not found): Verify the app name and workspace URL are correct, the app is deployed and running, and the endpoint path exists.
- Git deployment fails: For private repositories, verify the app's service principal has a Git credential configured. If deploying through CLI/API/DABs, create the app first, then add the Git credential.
AppKit docs
Access the AppKit API reference, component docs, and plugin docs from the terminal:
npx @databricks/appkit docs # browse the documentation index
npx @databricks/appkit docs --full # full index with all API entries
npx @databricks/appkit docs "<query-or-doc-path>" # view a specific section or file
Run without arguments to browse the index. Useful when building with an AI coding assistant. Point it here instead of guessing API shapes, or view the AppKit reference on this site.
Where to next
Browse the templates catalog to start building, or add capabilities to your app: Lakebase Postgres for persistent storage or Agent Bricks for AI features.