Quickstart

This quickstart takes one Databricks agent from an empty directory to a gated production promotion. You will scaffold a repo, deploy an immutable artifact to a Unity Catalog Volume, request a release gate, and approve the promotion.

Prerequisites

• Node.js 22+ and pnpm 10.28+
• The databricks CLI authenticated to your workspace (databricks auth login)
• A Unity Catalog Volume you can write to (for release artifacts), e.g. /Volumes/main/runway/artifacts
• Access to a Runway control plane (its URL and your organization id)

Set your connection once so every command targets the right control plane and tenant:

export RUNWAY_API_URL="https://runway.your-workspace.databricksapps.com"
export RUNWAY_ORG="org-acme"
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"

1. Scaffold a governed agent

npx @fabricorg/runway-cli init support-agent
cd support-agent
pnpm install

fr init writes a ready-to-ship RAG support agent: the agent job, a Databricks Asset Bundle (databricks.yml), a Databricks App manifest (app.yaml), a pre-wired GitHub Actions pipeline, and the Runway delivery manifest (runway.json).

{
  "name": "support-agent",
  "template": "rag-agent",
  "gate": "eval-suite",
  "artifact": ".fabricharness/build/databricks-app",
  "artifactVolume": "/Volumes/main/runway/artifacts"
}

See the runway.json reference for every field.

2. Build the bundle

pnpm build   # fh build --target databricks-app → .fabricharness/build/databricks-app

3. Deploy to dev and request the gate

fr deploy

fr deploy does five things, in order:

1. Stages the built bundle to a content-addressed UC Volume path (<artifactVolume>/<app>/<sha256>) and records the digest.
2. Registers the app in the catalog on first run (runway.app_register).
3. Verifies and admits the build with source/Harness/component provenance (runway.artifact_register).
4. Requests a dev deployment by stable artifact id (runway.deploy_request).
5. Requests the quality gate (runway.gate_evaluate).

If the gate fails, fr deploy exits with code 2 (governance block). Fix the workload and redeploy — re-evaluation is allowed until a promotion is approved.

4. Promote to production

fr promote

fr promote records a reviewer approval (runway.promotion_approve) for the latest gate_passed deployment. Approval must pass three policies:

• Provenance — the verdict came from Fabric Experiments with an evidence URI.
• Freshness — the evidence is within the TTL window.
• Separation of duty — you are not the person who requested the deploy.

Approval does not deploy prod. A separate trusted worker executes the production deploy (runway.promotion_execute) — humans, the CLI, MCP, and CI never run prod directly. See gates and evidence for why.

Explore the flow locally (no workspace)

To see the whole governed domain without a Databricks workspace, run the console and the demo from a checkout of the Runway repo:

pnpm install
pnpm build
pnpm --filter @fabric-runway/console dev   # http://localhost:3100
pnpm demo                                   # governed flow against mock adapters
pnpm demo:cli                               # exercises the real databricks CLI edge (stub binary)

The seeded console shows an operator overview, application catalog, deployment details, queryable logs, delivery analytics, release insights, observability, approvals, audit, environment metadata, and Fabric-family integrations for two example organizations.

Next steps