# Configuration

This guide covers environment variables and configuration options for AppKit applications.

## App deployment configuration[​](#app-deployment-configuration "Direct link to App deployment configuration")

### `app.yaml` file[​](#appyaml-file "Direct link to appyaml-file")

The `app.yaml` file configures your app's runtime environment in Databricks Apps.

**Basic example:**

```yaml
command:
  - node
  - build/index.mjs
env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse

```

### Command specification[​](#command-specification "Direct link to Command specification")

Specify how to start your app in the `command` field:

```yaml
command:
  - node
  - build/index.mjs

```

This runs the production build of your AppKit server (created by `npm run build`).

### Binding a SQL warehouse[​](#binding-a-sql-warehouse "Direct link to Binding a SQL warehouse")

To use the analytics plugin, bind a SQL warehouse in your `app.yaml`:

```yaml
env:
  - name: DATABRICKS_WAREHOUSE_ID
    valueFrom: sql-warehouse

```

This makes the warehouse ID available to your app at runtime. The `valueFrom: sql-warehouse` directive tells Databricks Apps to inject the configured warehouse ID.

### Binding Unity Catalog volumes (files plugin)[​](#binding-unity-catalog-volumes-files-plugin "Direct link to Binding Unity Catalog volumes (files plugin)")

The files plugin uses named volumes. Each volume key maps to an environment variable `DATABRICKS_VOLUME_{KEY_UPPERCASE}`:

```yaml
env:
  - name: DATABRICKS_VOLUME_UPLOADS
    valueFrom: volume
  - name: DATABRICKS_VOLUME_EXPORTS
    valueFrom: volume

```

See the [Files plugin](./docs/plugins/files.md) documentation for details.

For advanced configuration options (authorization, networking, resource limits), see the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation.

## Environment variables[​](#environment-variables "Direct link to Environment variables")

### Required for Databricks Apps deployment[​](#required-for-databricks-apps-deployment "Direct link to Required for Databricks Apps deployment")

These are typically **provided by Databricks Apps runtime** (exact set can vary by platform/version):

| Variable              | Description                                             |
| --------------------- | ------------------------------------------------------- |
| `DATABRICKS_HOST`     | Workspace URL (e.g. `https://xxx.cloud.databricks.com`) |
| `DATABRICKS_APP_PORT` | Port to bind (default: `8000`)                          |
| `DATABRICKS_APP_NAME` | App name in Databricks                                  |

### Required for SQL queries (analytics plugin)[​](#required-for-sql-queries-analytics-plugin "Direct link to Required for SQL queries (analytics plugin)")

| Variable                  | Description      | How to Set                                |
| ------------------------- | ---------------- | ----------------------------------------- |
| `DATABRICKS_WAREHOUSE_ID` | SQL warehouse ID | In `app.yaml`: `valueFrom: sql-warehouse` |

See the [App deployment configuration](#app-deployment-configuration) section above for details on how to bind this variable.

### Optional variables[​](#optional-variables "Direct link to Optional variables")

| Variable                  | Description                       | Default               |
| ------------------------- | --------------------------------- | --------------------- |
| `DATABRICKS_WORKSPACE_ID` | Workspace ID                      | Auto-fetched from API |
| `NODE_ENV`                | `"development"` or `"production"` | —                     |
| `FLASK_RUN_HOST`          | Host to bind                      | `0.0.0.0`             |

### Telemetry (optional)[​](#telemetry-optional "Direct link to Telemetry (optional)")

| Variable                      | Description                      |
| ----------------------------- | -------------------------------- |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
| `OTEL_SERVICE_NAME`           | Service name for traces          |

## Local development authentication[​](#local-development-authentication "Direct link to Local development authentication")

For local development, you need to authenticate with Databricks. Choose one of the following options:

### Option 1: Databricks CLI authentication (recommended)[​](#option-1-databricks-cli-authentication-recommended "Direct link to Option 1: Databricks CLI authentication (recommended)")

Configure authentication once using the Databricks CLI:

```bash
databricks auth login --host [host] --profile [profile-name]

```

If you use `DEFAULT` as the profile name, you can run your dev server directly:

```bash
npm run dev

```

To run with a specific profile, set the `DATABRICKS_CONFIG_PROFILE` environment variable:

```bash
DATABRICKS_CONFIG_PROFILE=my-profile npm run dev

```

Note: Some Databricks SDK versions use `DATABRICKS_PROFILE` instead of `DATABRICKS_CONFIG_PROFILE`.

### Option 2: Environment variables[​](#option-2-environment-variables "Direct link to Option 2: Environment variables")

```bash
export DATABRICKS_HOST="https://xxx.cloud.databricks.com"
export DATABRICKS_TOKEN="dapi..."
export DATABRICKS_WAREHOUSE_ID="abc123..."
npm run dev

```

### Option 3: `.env` file (auto-loaded by AppKit)[​](#option-3-env-file-auto-loaded-by-appkit "Direct link to option-3-env-file-auto-loaded-by-appkit")

Create a `.env` file in your project root (add to `.gitignore`!):

```bash
DATABRICKS_HOST=https://xxx.cloud.databricks.com
DATABRICKS_TOKEN=dapi...
DATABRICKS_WAREHOUSE_ID=abc123...

```

Then run:

```bash
npm run dev

```

## Advanced configuration[​](#advanced-configuration "Direct link to Advanced configuration")

For advanced Databricks Apps configuration (authorization, networking, resource limits), refer to the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation.

## See also[​](#see-also "Direct link to See also")

* [App management](./docs/app-management.md) - Deploying and managing apps
* [Plugins](./docs/plugins.md) - Plugin configuration options