Build real solutions on Databricks — with best practices built in.
Start with sample data, or your own. Same engine either way.
Describe what you want to build, and an AI agent builds it for you — on Databricks, done the right way. A quick demo, an internal proof of concept, or a pilot on your real data: same engine. What you get back is a real, running solution in your workspace — yours to inspect, edit, and keep.
Two ways to use it: run the full app for chat, a file viewer, and a template gallery, or install the CLI skill and work from your terminal. Same library, same results.
Trying an idea? The agent generates realistic synthetic data you can click through in minutes. Ready for the real thing? Point it at the tables you already have. You don't switch tools when you move from sandbox to production — same engine, same patterns, same result.
No improvisation, no guessing at the right pattern. The agent works from a curated library of Databricks best practices and builds every resource the right way — governed, owned, and inspectable. Show it to your customer on Monday with confidence.
Every solution comes with an editable, live architecture diagram — the "Data + AI Platform" picture, wired to the resources it actually builds. Author it on a Lucidchart-style canvas (drag components, wire flows, drop in partner logos), then export to PNG or SVG for a deck or a one-pager.
Fork a vetted blueprint and tell the agent what to change for your customer or industry. Publish any finished solution as a template your whole org can reuse — reskin one industry for another, swap a pattern, recombine for a new pitch. Every solution becomes a starting point for the next.
Prefer your terminal? Install the Solution Builder skill into any Claude Code project and drive it from the CLI. Want a guided UI with chat, a file viewer, and live diagrams? Use this app. Same library, same outputs, same deploys — pick whichever fits the moment.
Important
Beta — account admin access needed. Solution Builder is in beta and needs the all-apis OAuth scope to use the full Databricks API surface reliably. Granting that scope requires account admin rights. For now, run it in a development or sandbox workspace, not production. No admin rights? Ask an admin to grant the scope after deploy (see Deploy to Databricks) or to run the app for you.
# 1. Clone
git clone https://github.com/databricks-solutions/solution-builder.git
cd solution-builder/app
# 2. Authenticate the Databricks CLI (one-time)
databricks auth login --host https://<workspace-url> --profile MY_WORKSPACE
# 3. Configure env
cp .env.example .env
# edit .env → DATABRICKS_CONFIG_PROFILE=MY_WORKSPACE
# 4. Install deps
uv sync # Python (creates .venv)
bun install # Frontend
# 5. Run (backend :8000 + frontend :5173, hot reload, opens browser)
./scripts/dev.shPGLite auto-provisions a local Postgres — no DB setup required. Reset with RESET_DB=1 ./scripts/dev.sh.
Prerequisites: uv · bun · Databricks CLI v0.239.0+ authenticated to a workspace.
Environment variables — click to expand
All of these live in app/.env (copy from app/.env.example). The bold ones are the minimum to boot.
| Variable | Required | Default | Purpose |
|---|---|---|---|
DATABRICKS_CONFIG_PROFILE |
✅ | DEFAULT |
Profile from ~/.databrickscfg (set via databricks auth login) |
DATABRICKS_HOST / DATABRICKS_TOKEN |
alt | — | Direct token auth (CI/CD); use instead of the profile |
LAKEBASE_DATABASE_PATH |
optional | — | projects/<id>/branches/<id>/databases/<name> — omit to use PGLite |
USE_PGLITE |
optional | — | Force PGLite even if LAKEBASE_DATABASE_PATH is set |
ANTHROPIC_LLM_ENDPOINT |
✅ | databricks-claude-sonnet-4-6 |
Model the agent talks to (via FMAPI Anthropic bridge) |
ANTHROPIC_BASE_PATH |
✅ | serving-endpoints/anthropic |
FMAPI bridge path — switch to ai-gateway/anthropic for AI Gateway endpoints |
AI_GATEWAY |
✅ | databricks-claude-opus-4-7 |
Primary AI Gateway endpoint for the backend |
AI_GATEWAY_MINI |
✅ | databricks-gpt-5-4-mini |
Cheap/fast endpoint for utility calls |
AI_GATEWAY_EMBEDDING |
✅ | databricks-qwen3-embedding-0-6b |
Embedding endpoint for template semantic search |
DAS_BRANCH |
optional | main |
Branch of databricks-agent-skills that dev.sh clones (legacy alias: AI_DEV_KIT_BRANCH) |
DEMO_PROMPT_GENERATOR_TRACKER_ENABLED |
optional | 1 |
Anonymous usage analytics — see the privacy note below; set to 0 to opt out |
See app/.env.example for the full annotated list with inline guidance.
Anonymous usage analytics are on by default. We collect aggregated, anonymized events (page views, feature usage counts) only to understand what's working and what needs improvement — never for sales contact. The underlying
dbdemos-trackerpackage filters at the source so events fire only for@databricks.comusers; external installations send nothing. SeePRIVACY.mdfor the full list of fields. Opt out anytime withDEMO_PROMPT_GENERATOR_TRACKER_ENABLED=0.
Type checking:
cd app
npx tsc --noEmit # TypeScript
uv run mypy src # Python| Mode | Where it runs | Auth model | Use case |
|---|---|---|---|
| Local dev | Your laptop | ~/.databrickscfg profile |
Day-to-day development with hot reload |
| Databricks App | A Databricks workspace | App service principal (OAuth) | Shared deployment for your team |
| Electron | Your laptop, packaged | ~/.databrickscfg profile |
Standalone desktop app for end-users |
Deploy to Databricks (production) — click to expand
The app deploys as a Databricks Asset Bundle — Lakebase database, App resource, model-serving permissions, and source code in one command.
cd app
# One-time setup
databricks auth login --host https://<workspace-url> --profile MY_WORKSPACE
cp databricks.prod.yml.example databricks.prod.yml
# fill in workspace.profile, variables, env
# Deploy
databricks bundle deploy
databricks bundle run demo-prompt-generator-appdatabricks.prod.yml is gitignored — it holds workspace-specific values (profile, app name, Lakebase instance, model endpoints).
Verify:
databricks apps get <your-app-name> --output json | jq -r '
"URL: \(.url)",
"App: \(.app_status.state)",
"Deploy: \(.active_deployment.status.state) — \(.active_deployment.status.message)"
'
# app_status.state should reach "RUNNING"Post-deploy: grant the app all-apis OAuth scope. This step requires account admin access on the Databricks account — the app is in beta and currently depends on the full all-apis scope to function reliably, which is why we recommend deploying only to development/sandbox workspaces for now. Each databricks bundle deploy may rotate the OAuth integration ID, so re-run this whenever you redeploy:
./scripts/set-app-oauth-scopes.sh # uses target=prod
./scripts/set-app-oauth-scopes.sh --target prod # explicitThe script reads the app name from databricks.<target>.yml, auto-detects your account-level CLI profile, finds the matching OAuth integration, and grants all-apis. Idempotent.
Config flow:
databricks.prod.yml (env:) → build.sh reads via `databricks bundle summary`
→ writes .build/app.yml (env: 1:1 copy)
→ Databricks Apps runtime exports env vars into the container
→ backend reads them via Pydantic Settings
Bundle targets: prod (default) and staging. Add a third with two files: databricks.qa.yml{,.example} + a stub targets.qa: in databricks.yml.
Staging-specific setup:
cd app
cp databricks.staging.yml.example databricks.staging.yml
databricks bundle deploy -t staging
./scripts/set-app-oauth-scopes.sh --target staging
# Lakebase UI: grant the new staging SP CAN_CONNECT_AND_CREATE on the project.
databricks bundle run demo-prompt-generator-app -t stagingAuth model (deployed): The app authenticates as a service principal that Databricks Apps creates and binds to the deployment. The SDK reads DATABRICKS_CLIENT_ID / DATABRICKS_CLIENT_SECRET from the runtime and mints OAuth tokens automatically — no PATs are stored anywhere. End-users browsing the app authenticate via OAuth and the agent runs Databricks CLI commands on their behalf via x-forwarded-access-token.
Build the Electron desktop app — click to expand
Bundles Python, the FastAPI backend, the React frontend, and Electron into a single .dmg / .exe / .AppImage.
cd app
./scripts/build-electron.sh # Build for current arch
./scripts/build-electron.sh --arch arm64 # Apple Silicon
./scripts/build-electron.sh --arch x64 # Intel Mac / Linux
./scripts/build-electron.sh --arch universal # Mac universal binaryOutput lands in app/dist-electron/. First launch prompts for a profile via the in-app config UI.
To cut a versioned release:
./scripts/release.sh patch # 0.1.0 → 0.1.1
./scripts/release.sh minor # 0.1.0 → 0.2.0
./scripts/release.sh 1.2.3 # explicit versionInstall the Solution Builder skill (and the Databricks Agent Skills, via the Databricks CLI) into your ~/.claude/ once, then drive everything from any terminal:
bash <(curl -sL https://raw.githubusercontent.com/databricks-solutions/solution-builder/main/install.sh)cd into any project, run claude, and the skill loads automatically — the agent can design, write, and build Databricks assets end-to-end from the terminal.
Flags:
| Flag | Behavior |
|---|---|
| (none) | Installs the skill to ~/.claude/skills/ and the Databricks Agent Skills (via the Databricks CLI) |
--project |
Installs the skill into ./.claude/skills/ in the current directory instead |
--branch <name> |
Pulls the skill from a non-main branch |
Same library as the app, same outputs — pick whichever surface fits the moment. Use the app when you want chat + file viewer + gallery; use the CLI when you want to stay in your terminal.
Lakebase tables
| Table | Purpose |
|---|---|
users |
User configuration — email, preferred Databricks profile |
projects |
Top-level containers — name, description, stage, compute resources, session state |
project_files |
Files tracked per project — compressed content, SHA-256 hash, sync timestamps |
project_stars |
User favorites (star/unstar) |
project_shares |
Project sharing between users (read-only access) |
messages |
Chat messages within a project (user/assistant/system roles, reasoning data) |
executions |
Agent execution state — enables session resumption after page refresh |
templates |
Published project snapshots — name, industry, capabilities, pgvector embedding |
template_content |
Files stored in a template (compressed, like project files) |
Tables are auto-created on startup via SQLModel + DDL migrations in lakebase.py.
API surface (all routes prefixed with /api)
Projects
| Method | Path | Description |
|---|---|---|
GET |
/projects |
List current user's projects |
POST |
/projects |
Create a new project (LLM generates name/description) |
GET |
/projects/{id} |
Get project details |
PATCH |
/projects/{id} |
Update project name/description |
PATCH |
/projects/{id}/resources |
Update compute resources |
DELETE |
/projects/{id} |
Delete a project and its files |
POST |
/projects/{id}/sync |
Sync files between disk and database |
POST |
/projects/{id}/star |
Toggle starred status |
POST |
/projects/{id}/share |
Share project with another user |
GET |
/projects/{id}/shares |
List shares for a project |
DELETE |
/projects/{id}/share/{share_id} |
Remove a share |
GET |
/shared-projects |
List projects shared with current user |
Project files
| Method | Path | Description |
|---|---|---|
GET |
/projects/{id}/files |
List files in a project |
GET |
/projects/{id}/files/{path} |
Read file content |
GET |
/projects/{id}/download |
Download project as zip |
GET |
/projects/{id}/deployed-resources |
Get deployed Databricks resource links |
Messages
| Method | Path | Description |
|---|---|---|
GET |
/projects/{id}/messages |
Get message history |
POST |
/projects/{id}/messages |
Add a message |
DELETE |
/projects/{id}/messages |
Clear message history |
POST |
/projects/{id}/session/clear |
Clear agent session |
Agent
| Method | Path | Description |
|---|---|---|
POST |
/invoke_agent |
Start agent execution, returns execution_id |
POST |
/stream_progress/{execution_id} |
SSE stream of agent events |
POST |
/stop_stream/{execution_id} |
Cancel running execution |
GET |
/projects/{id}/execution |
Get active execution for a project |
Templates
| Method | Path | Description |
|---|---|---|
GET |
/templates |
List templates (filterable by status/industry) |
GET |
/templates/{id} |
Get template details |
GET |
/templates/{id}/files |
List template files |
GET |
/templates/{id}/files/{path} |
Read template file content |
POST |
/templates/search |
Semantic search via pgvector |
POST |
/templates/from-project/{id} |
Publish a project as a template |
POST |
/templates/{id}/status |
Update review status (admin) |
POST |
/templates/{id}/create-project |
Fork template into a new project |
POST |
/templates/{id}/open-project |
Open existing project for a template |
PUT |
/templates/{id}/update-from-project/{id} |
Sync template from updated project |
GET |
/templates/by-project/{id} |
Find template linked to a project |
PATCH |
/templates/{id}/owner |
Transfer template ownership |
DELETE |
/templates/{id} |
Delete a template |
Skills & resources
| Method | Path | Description |
|---|---|---|
GET |
/projects/{id}/skills |
List available Databricks Agent Skills |
GET |
/projects/{id}/skills/{name}/files |
List files in a skill |
GET |
/projects/{id}/skills/{name}/files/{path} |
Read skill file content |
POST |
/projects/{id}/skills/refresh |
Re-sync skills from Databricks Agent Skills |
GET |
/projects/{id}/system-prompt |
Preview the agent's system prompt |
GET |
/resources/clusters |
List available clusters |
GET |
/resources/warehouses |
List available SQL warehouses |
GET |
/resources/catalogs |
List Unity Catalog catalogs |
GET |
/resources/schemas |
List schemas in a catalog |
GET |
/resources/defaults |
Get default resource settings |
POST |
/resources/refresh |
Refresh cached resource lists |
Other
| Method | Path | Description |
|---|---|---|
GET |
/version |
App version |
GET |
/health |
Health check |
GET |
/current-user |
Current Databricks user info |
GET |
/config/status |
Configuration status (DB, profiles, user) |
GET |
/constants/industries |
List of supported industries |
GET |
/constants/capabilities |
List of available capability blocks |
POST |
/capabilities/suggest |
AI-powered capability suggestions for a scenario |
POST |
/block-factory/process |
Decompose a document into context blocks |
Project structure
solution-builder/
├── app/ # Full-stack application (see app/CLAUDE.md)
│ ├── src/demo_prompt_generator/
│ │ ├── backend/
│ │ │ ├── app.py # FastAPI entry point
│ │ │ ├── models.py # SQLModel tables + Pydantic schemas
│ │ │ ├── router.py # Singleton router, imports all route modules
│ │ │ ├── core/ # App factory, config, DI, DB engine, static serving
│ │ │ ├── routes/ # API routes (agent, projects, files, messages, etc.)
│ │ │ └── services/ # Business logic (agent, LLM, file sync, skills, templates)
│ │ └── ui/ # React frontend
│ │ ├── routes/ # TanStack Router file-based routes
│ │ ├── components/ # UI components (project/, layout/, ui/, template/)
│ │ ├── lib/ # API clients, utilities, config
│ │ ├── hooks/ # Custom React hooks
│ │ └── styles/ # Tailwind CSS globals
│ ├── databricks.yml # DAB config — generic resource shape
│ ├── databricks.prod.yml.example # Per-deployment config template (gitignored when filled in)
│ ├── pyproject.toml # Python deps (use uv, never pip)
│ ├── package.json # Frontend deps (use bun)
│ ├── scripts/ # dev.sh, build.sh, build-electron.sh, release.sh
│ └── .env.example # Local-dev environment variable template
├── .claude/skills/databricks-solution-builder/
│ └── references/blocks/ # Context blocks (Solution Builder Skill)
│ ├── capabilities/ # 26+ Databricks feature blocks
│ ├── domains/ # Industry verticals
│ └── patterns/ # Analytical patterns
├── docs/ # Diagrams + screenshots used in this README
├── tests/ # Playwright E2E tests
├── install_demo_generator_skill.sh # Standalone skill installer
└── playwright.config.ts # Test config (targets localhost:9000)
Extending — adding a context block
Create a Markdown file in the appropriate .claude/skills/databricks-solution-builder/references/blocks/ subdirectory (domains/, capabilities/, or patterns/) with YAML frontmatter:
---
name: My New Block
slug: my-new-block
category: capability
tags: [tag1, tag2]
description: One-line summary of what this block provides.
related: [genie, retail]
---
Block content goes here — terminology, best practices, configuration guidance, etc.Blocks on disk are automatically available to the agent's system prompt for all new projects.
License & attribution — click to expand
Licensed under the Databricks License. Built on top of and powered by the following open-source projects.
| Package | Version | License | Project URL |
|---|---|---|---|
| claude-agent-sdk | ≥0.2.83 | MIT | https://github.com/anthropics/claude-agent-sdk |
| databricks-sdk | ≥0.114.0 | Apache-2.0 | https://github.com/databricks/databricks-sdk-py |
| databricks-connect | ≥16.1,<16.2 | Databricks | https://docs.databricks.com/dev-tools/databricks-connect.html |
| databricks-agent-skills | — | Databricks | https://github.com/databricks/databricks-agent-skills |
| Package | Version | License | Project URL |
|---|---|---|---|
| react | 19.2.3 | MIT | https://github.com/facebook/react |
| vite | ^8.0.10 | MIT | https://github.com/vitejs/vite |
| @tanstack/react-router | 1.145.7 | MIT | https://github.com/TanStack/router |
| @tanstack/react-query | 5.90.16 | MIT | https://github.com/TanStack/query |
| tailwindcss | ^4.2.4 | MIT | https://github.com/tailwindlabs/tailwindcss |
| @radix-ui/* | ^1.x | MIT | https://github.com/radix-ui/primitives |
| shadcn/ui | — | MIT | https://github.com/shadcn-ui/ui |
| motion | 12.24.10 | MIT | https://github.com/motiondivision/motion |
| lucide-react | ^0.575.0 | ISC | https://github.com/lucide-icons/lucide |
| @xyflow/react | ^12.10.2 | MIT | https://github.com/xyflow/xyflow |
| @monaco-editor/react | ^4.7.0 | MIT | https://github.com/suren-atoyan/monaco-react |
| embla-carousel-react | ^8.6.0 | MIT | https://github.com/davidjerleke/embla-carousel |
| electron | ^33.4.11 | MIT | https://github.com/electron/electron |
| playwright | — (npx) | Apache-2.0 | https://github.com/microsoft/playwright |
Caution
Use at your own risk. Solution Builder spawns AI agents that write code and create resources on your behalf, with full permission.
Shared container. Deployed as a Databricks App, every user's session runs inside the same container with full access to whatever your identity can reach — Unity Catalog objects, jobs, pipelines, dashboards, and more. An agent can reach beyond a single project. Share the app only with people you trust, or run one instance per user (improving soon).
Deploy to an isolated or sandbox workspace — not a sensitive, production-grade one — and don't point it at data you can't afford to lose. Software provided "as is"; see LICENSE.
Built by Databricks Field Engineering.
Describe it. Ship it. Iterate on what matters.