Harness bridge

The Databricks skill delegates scaffolding, build, and deploy to Fabric Harness. The bridge maps fabric-cli databricks commands to fh invocations, strips unrelated secrets from the child environment, redacts tokens from all output, and gates live runs behind an explicit environment variable.

Compatibility negotiation

Before the bridge executes a Harness command, it checks both the installed CLI version and its machine-readable capabilities:

fh --version
fh capabilities --json

Desktop requires Fabric Harness CLI 6.7.4 or newer within the supported 6.x line (Node.js 22 or newer), CLI protocol 1, build manifest 2, both Databricks build targets, and the sdk.define-agent, preview, App build/deploy, and AI Gateway features. A CLI that does not provide the expected contract fails closed with an actionable compatibility error; there is no silent legacy fallback.

flowchart TD
  A[Fabric Desktop or fabric-cli] --> B[Databricks Harness bridge]
  B --> C[Resolve project-local or PATH fh]
  C --> D[Version range check]
  D --> E[Capability contract check]
  E --> F[Allow-listed environment and redaction]
  F --> G[Fabric Harness command]
  G --> H[Databricks App, Model Serving, or local mock]

Bundled templates declare compatible Harness package ranges (@fabric-harness/cli ^6.7.4, sdk/node ^6.5.0, databricks ^7.1.1, temporal ^2.2.3) and engines.node >=22. Desktop CI tests the minimum certified version and npm latest; Harness release CI can also pack an unpublished CLI and run it through this same bridge contract before release.

Local CLI and server mode

There are three related execution surfaces:

The bridge prefers a project-local node_modules/.bin/fh, then falls back to PATH. This keeps a project reproducible while still supporting a globally installed CLI. In server mode, credentials and the Harness executable belong on the server; the browser or remote client should never receive workspace tokens. Use TLS and server authentication whenever the server listens beyond loopback.

For local development, verify the selected executable and contract before a run:

command -v fh
fh --version
fh capabilities --json
fabric-cli databricks deploy --target databricks-app --preview

Commands

The bundled templates (governed-analytics-copilot, lakebase-rag-agent, data-engineering-agent) are copied directly from the app's resources; any other template name delegates to fh init. The default agent for run is analyst — override with --agent <name>.

Deploy targets

Note: databricks-serving is a wrapper target — the agent itself must already be reachable over HTTP (typically deployed first via databricks-app, with its URL stored as a Databricks secret). Deploy databricks-app before databricks-serving.

Live deploys require the Databricks CLI on your PATH; the serving target additionally needs Python with mlflow and databricks-sdk installed.

Security model

• Live gate — live run commands are disabled unless FABRIC_DATABRICKS_TEST=1 is set. Mock runs never require it.
• Secret stripping — before spawning fh, the bridge removes unrelated cloud credentials (AWS, Azure, Google, GitHub, OpenAI, Anthropic, Slack) from the child environment.
• Redaction — Databricks PATs (dapi...), bearer tokens, and other secret-shaped strings are replaced with ***REDACTED*** in all command output.
• Mock isolation — in mock mode the bridge deletes DATABRICKS_HOST, DATABRICKS_TOKEN, and OAuth variables from the child environment so a "mock" run can never accidentally reach a live workspace.
• Attribution — every run sets FABRIC_USER_AGENT=fabric-agents/<version> so requests are identifiable in Databricks audit logs.

--mock flag

--mock runs the command using MockDatabricksModelProvider, returning canned responses without making any live API calls. Use it for onboarding, CI, and local development when you don't have workspace credentials.

fabric-cli databricks run --mock
fabric-cli databricks build --target databricks-app --mock
fabric-cli databricks deploy --target databricks-app --preview --mock

Note: Of the bundled templates, only the Governed Analytics Copilot supports mock mode. The RAG and data engineering templates are live-only — see Templates.

Preview mode

--preview performs a dry-run deploy: it validates the bundle, resolves variables, and prints the deployment plan without creating or modifying any Databricks resources. Use it to review changes before a live deploy.

fabric-cli databricks deploy --target databricks-app --preview

Output includes:

• Resources that would be created, updated, or deleted.
• Variable resolutions (secrets redacted).
• Any validation errors that would block a live deploy.

No side effects occur in the workspace. Preview deploys don't require credentials, so they are safe to run in CI or during code review.

Workspace discovery on init

When you run databricks init from the chat agent with a connected Databricks source, the handler discovers workspace metadata before scaffolding and injects it into the generated project:

• The first running SQL warehouse (falling back to the first warehouse)
• The first non-system catalog (preferring main)
• The default schema in that catalog
• The first Genie space, if any

The scaffolded .env.example is pre-filled with these non-secret IDs, and fabric.config.ts is rewritten to reference process.env.* variables instead of literal values. Secrets are never written — only resource identifiers. If discovery fails, scaffolding still succeeds with placeholder values.

Mock-run happy path

The mock-run happy path lets a developer scaffold and validate a Databricks project without live credentials or workspace access.

1. Ensure fh is installed and on your PATH:

   command -v fh

2. Scaffold the project:

   fabric-cli databricks init --template governed-analytics-copilot

3. Run in mock mode:

   fabric-cli databricks run --mock --question "What tables are in main?"

   The agent executes with MockDatabricksModelProvider, returning canned responses. No API calls are made.

4. Validate the build target:

   fabric-cli databricks build --target databricks-app --mock

5. Preview deploy (still no side effects):

   fabric-cli databricks deploy --target databricks-app --preview --mock

6. Iterate on agent definitions and skills, then repeat steps 3–5.

7. Go live — set the live gate and credentials, then run without --mock:

   export FABRIC_DATABRICKS_TEST=1
   export DATABRICKS_HOST="https://<workspace-host>.cloud.databricks.com"
   export DATABRICKS_TOKEN="dapi..."
   fabric-cli databricks run --question "What tables are in main?"
   fabric-cli databricks deploy --target databricks-app

What you proved:

• Agent definitions parse correctly.
• Tools (sql, tables, table-info) are registered.
• Bundle structure is valid for the chosen target.
• No live credentials were required.

Credential passing

Always use short-lived environment variables. Never write secrets into generated files.

export DATABRICKS_HOST="https://<workspace-host>.cloud.databricks.com"
export DATABRICKS_TOKEN="<short-lived-pat>"
# Or for OAuth:
export DATABRICKS_CLIENT_ID="<service-principal-id>"
export DATABRICKS_CLIENT_SECRET="<service-principal-secret>"

Generated databricks.yml uses safe env var references:

workspace:
  host: ${DATABRICKS_HOST}
  auth_type: token

Required privileges and safe defaults

Safe defaults

• Explore mode allows only GET endpoints.
• Cluster mutations (start, stop, terminate) require ask or allow-all permission mode.
• Unity Catalog mutations (CREATE, DROP, ALTER) are gated behind ask or allow-all.
• The agent never writes secrets into scaffolded files.

Minimum privileges

Related

• Templates — the three bundled workload templates
• Fabric CLI reference — full fabric-cli command surface
• Troubleshooting — common errors and fixes