dbx-tools

Documentation - full package reference, guides, and API docs.

dbx-tools

Companion packages for Databricks developers building Databricks Apps, AppKit backends, Mastra agents, Genie workflows, and Model Serving integrations.

dbx-tools adds Mastra agents, model routing, Genie tools, search, email, Teams, Graphiti memory, tunnels, and reusable React surfaces to AppKit apps.

Add A Sandboxed Agent

import { createApp, server } from "@databricks/appkit";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const analyst = agents.createAgent({
  instructions: "Answer questions and use Python for analysis.",
});

await createApp({
  plugins: [server(), mastra({ agents: { analyst }, sandbox: "databricks" })],
});

Add Lakebase, Genie, Analytics, or other AppKit plugins when the agent needs durable threads or workspace tools.

Use With Native AppKit

Use native AppKit first when it already gives you the exact surface you need. AppKit has strong built-in plugins for Analytics, Genie, Files, Lakebase, Model Serving, Jobs, beta AI Search, and beta Agents, plus React UI primitives and hooks. dbx-tools is not a fork of that platform and should not replace AppKit for straightforward cases.

This repository tests AppKit and AppKit UI 0.81 as an exact pair. Prefer native database() for typed application entities, native code-agent discovery and curated skills for simple agents, @databricks/appkit/testing for plugin/app harnesses, and native evaluation contracts where they fit. The packages below remain for protocols and policy those surfaces do not replace.

Use these packages when the native surface gets repetitive or narrow for a real app:

• you need Databricks defaults before AppKit plugins initialize, such as Lakebase env discovery or layered config resolution;
• you want Mastra’s agent runtime, storage, tools, MCP, and broader ecosystem while still running inside AppKit with OBO auth and Databricks plugin tools;
• you want Genie Agent Mode SSE projected as typed async events that an agent or custom UI can consume, enrich, and turn into chart/data embeds;
• you want model selection by intent ("sonnet", "chat-fast") rather than wiring every app to one serving endpoint alias;
• you need a managed Graphiti memory sidecar backed by PostgreSQL, per-user graph groups, and a constrained AppKit MCP endpoint;
• you need local OpenAI-compatible development tooling on top of Databricks Model Serving;
• you want agent tools, federated search, index lifecycle helpers, reusable search components, or a Lakebase full-text provider around native AppKit AI Search;
• you need reusable UI surfaces for Mastra chat or human-approved email rather than a one-off component in each app.

What This Adds

• AppKit app defaults — auto-configure Lakebase/Postgres env through core config sources, access AppKit execution context safely, and look up sibling plugins with typed helpers.
• Core configuration and locking — resolve scoped settings lazily from constant data, the environment, project .env files, validated bundles, or App YAML with explicit runtime and source overrides; install binaries atomically; and serialize critical sections across threads, local processes, or replicas with process, file, and Postgres advisory locks.
• Mastra inside AppKit — register one or more Mastra agents as an AppKit plugin with OBO auth, Lakebase-backed storage/memory, independently configured workspace file access, skills, and sandboxing, model selection, history, threads, feedback, and scoped route exposure.
• Genie as agent tools — use Genie Agent Mode SSE by default to stream reasoning, SQL, query output, and synthesized answers as typed events; expose Genie metadata and starter questions. Agent Mode charts its inline rows through render_data; the Conversation API polling opt-out provides statement-backed chart and data embeds when an app needs them.
• Model Serving ergonomics — turn loose model names such as "sonnet" or "chat-fast" into concrete Databricks serving endpoints using workspace catalogues, fuzzy matching, class ceilings, cache, and fallbacks.
• OpenAI-compatible local proxy — point OpenAI-shaped clients at Databricks Model Serving without hand-managing Databricks auth or endpoint ids.
• Managed Graphiti memory - run the unified Python Graphiti runtime with persistent embedded PostgreSQL or Lakebase-backed PostGraph storage; enforce per-user graph groups; and republish a constrained MCP surface through AppKit.
• Approval-gated email workflows — give agents a send_email tool that suspends for human approval, supports SMTP or local outbox mode, derives safe senders, and renders Markdown email.
• Web search and fetch tools — give agents web_search (the Databricks native web-search tool, on its own Gemini/GPT web-capable model, returning an answer plus citations) and web_fetch (page contents) with an optional URL allow-list and per-tool approval gating.
• AI Search extensions and Lakebase full text - native AppKit aiSearch owns Vector Search queries, OBO, caching, reranking, pagination, and the React query hook. The dbx-tools search packages add agent tools, universal search, index creation/sync/seed helpers, SearchBox / SearchResults, and lakebaseAiSearch, a PostgreSQL full-text provider with the same AppKit query contract.
• Teams bot endpoint and Adaptive Cards — give an app a real Bot Framework messaging endpoint (inbound JWT validated, replies delivered over the Connector API), compile an agent’s small card spec into a schema-valid Adaptive Card, and render a whole Teams conversation in React.
• A Postgres message bus — broadcast a typed envelope to every app instance over LISTEN/NOTIFY with automatic sender context, plus optional persistence so a subscriber that missed a message can replay history by cursor.
• A gated public URL for any command — dbx tunnel -- <command> fronts a process with a portr tunnel and an email one-time-code gate, for the case that is not an AppKit app at all.
• Reusable React surfaces — provide AppKit/Tailwind/Bun foundations, a Mastra chat UI with a persistent dock/overlay assistant host, plus React Email approval, preview, compose, and delivery components.
• Shared browser-safe contracts — keep UI, server, tests, and tools aligned with zod schemas for Mastra routes, Genie events, model lookup, email payloads, and selected Databricks SDK shapes.
• Reusable brand context — validate one YAML or JSON source for product names, assets, colors, typography, and LLM writing voice, then consume it from Node, React, browser helpers, or generated JSON Schema.
• Databricks infrastructure helpers — resolve workspace identity, cloud region, public IPs, Zerobus endpoints, and Databricks SDK cancellation without binding every package to AppKit.

Repository Setup And Full Example

Install dependencies and type-check the workspace:

bun install
bun run --filter '*' compile

For AppKit apps, the most common entrypoint is the Mastra plugin:

import { analytics, createApp, lakebase, server } from "@databricks/appkit";
import { agents, genie, mastra } from "@dbx-tools/appkit-mastra";

const analyst = agents.createAgent({
  name: "analyst",
  instructions: `Answer with Databricks context.\n\n${genie.GENIE_INSTRUCTIONS}`,
  tools(plugins) {
    return {
      ...plugins.analytics.toolkit(),
      ...plugins.genie?.toolkit(),
    };
  },
});

await createApp({
  plugins: [
    server(),
    analytics(),
    lakebase(),
    mastra({
      agents: { analyst },
      defaultAgent: "analyst",
      genie: { spaces: { sales: "01ef..." } },
    }),
  ],
});

That single plugin registration can provide agent streaming routes, model resolution, Genie-backed data tools, durable Lakebase storage, chat history, thread management, feedback, and MCP exposure.

Use @dbx-tools/ui-mastra on the client side for the matching chat UI:

import { MastraChat } from "@dbx-tools/ui-mastra/react";

export function App() {
  return <MastraChat agentId="analyst" threadPlacement="auto" showModelPicker />;
}

For an app-wide assistant that survives route navigation, use MastraAssistant above the route outlet. It provides a configurable floating launcher, dock/overlay panel, resize behavior, external open(context) control, and typed per-turn Mastra request context without owning authentication.

Feature Packages

Use case	Packages
AppKit defaults	[@dbx-tools/appkit](/packages/appkit), [@dbx-tools/cli/appkit](/packages/cli)
AppKit-hosted agents	[@dbx-tools/appkit-mastra](/packages/appkit-mastra), [@dbx-tools/shared-mastra](/packages/shared-mastra)
Genie streaming and schemas	[@dbx-tools/genie](/packages/genie), [@dbx-tools/shared-genie](/packages/shared-genie)
Model Serving selection	[@dbx-tools/model](/packages/model), [@dbx-tools/shared-model](/packages/shared-model)
Local model gateway	[@dbx-tools/appkit-model-gateway](/packages/appkit-model-gateway), [@dbx-tools/shared-model-gateway](/packages/shared-model-gateway), [@dbx-tools/cli/model-gateway](/packages/cli)
Databricks runtime utilities	[@dbx-tools/auth](/packages/auth), [@dbx-tools/databricks](/packages/databricks)
Lakebase parsing and discovery	[@dbx-tools/lakebase](/packages/lakebase), [@dbx-tools/cli/lakebase-proxy](/packages/cli)
Databricks OAuth tokens	[@dbx-tools/auth](/packages/auth), [@dbx-tools/cli/auth](/packages/cli)
Public tunnel + access gate	[@dbx-tools/tunnel](/packages/tunnel), [@dbx-tools/cli/tunnel](/packages/cli)
Passwordless authentication	[@dbx-tools/auth-gate](/packages/auth-gate), [@dbx-tools/shared-auth](/packages/shared-auth), [@dbx-tools/ui/auth](/packages/ui)
Configuration and local locks	[@dbx-tools/core](/packages/core)
Email workflows	[@dbx-tools/email](/packages/email), [@dbx-tools/shared-email-template](/packages/shared-email-template), [@dbx-tools/shared-email](/packages/shared-email), [@dbx-tools/ui/email](/packages/ui)
Web search and fetch	[@dbx-tools/appkit-web-search](/packages/appkit-web-search)
Graphiti runtime and AppKit	[@dbx-tools/appkit-graphiti](/packages/appkit-graphiti), [dbx-tools-graphiti](/packages/py-graphiti)
Postgres locks and message bus	[@dbx-tools/postgres](/packages/postgres)
AI Search extensions	[@dbx-tools/search](/packages/search), [@dbx-tools/shared-search](/packages/shared-search), [@dbx-tools/ui/search](/packages/ui)
Teams chat and cards	[@dbx-tools/teams](/packages/teams), [@dbx-tools/shared-teams](/packages/shared-teams), [@dbx-tools/ui-teams](/packages/ui-teams)
React/AppKit UI	[@dbx-tools/ui](/packages/ui), [@dbx-tools/ui-mastra](/packages/ui-mastra), [@dbx-tools/ui/auth](/packages/ui), [@dbx-tools/ui/email](/packages/ui)
Brand context and assets	[@dbx-tools/shared-core](/packages/shared-core), [@dbx-tools/core](/packages/core), [@dbx-tools/ui/branding](/packages/ui)
Databricks infrastructure	[@dbx-tools/databricks](/packages/databricks), [@dbx-tools/databricks-zerobus](/packages/databricks-zerobus)
Portable filesystems	[@dbx-tools/shared-fs](/packages/shared-fs), [@dbx-tools/fs](/packages/fs)
Shared utilities	[@dbx-tools/shared-core](/packages/shared-core), [@dbx-tools/core](/packages/core), [@dbx-tools/path](/packages/path)
Commander args from Zod	[@dbx-tools/cli-args](/packages/cli-args)
The dbx CLI	[@dbx-tools/cli](/packages/cli), [@dbx-tools/cli/appkit](/packages/cli), [@dbx-tools/cli/auth](/packages/cli), [@dbx-tools/cli/tunnel](/packages/cli)

Read the package README for each feature area. They are written as the package-level source of truth: key features, import examples, configuration or runtime behavior, module maps, and links to adjacent packages.

Python Packages

Install the published Python packages by distribution name:

uv add dbx-tools-graphiti

The Python packages support Python 3.11 through the Python 3 release line.

The root uv workspace contains only the internal Graphiti adapter:

Package	Purpose
[dbx-tools-graphiti](/packages/py-graphiti)	Runs Graphiti REST, MCP, PostGraph storage, and PythonMonkey-backed Databricks model routing.

Load One Brand File

The root [branding/brand.yaml](https://github.com/reggie-db/dbx-tools/blob/main/branding/brand.yaml) is the canonical dbx tools context and points at the reusable SVG assets beside it. The same schema accepts JSON.

import { brandFiles } from "@dbx-tools/core";

const brandContext = await brandFiles.loadBrandContext();

Use brandUtils.BrandContextSchema from @dbx-tools/shared-core in browser-safe code or structured LLM tools. Use @dbx-tools/ui/branding/react and @dbx-tools/ui/branding/browser to render or apply the resulting context.

Common Workflows

Add AppKit Defaults

Use [@dbx-tools/appkit](/packages/appkit) when an AppKit backend needs the setup code you would otherwise repeat in every app: Lakebase env resolution, config lookup, Databricks SDK cancellation bridging, execution context fallback, and typed sibling plugin access.

import { lakebase, server } from "@databricks/appkit";
import { appkit } from "@dbx-tools/appkit";

await appkit.createApp({
  plugins: [server(), lakebase()],
});

Resolve Models By Intent

Use [@dbx-tools/model](/packages/model) when a UI, agent, or CLI should ask for a model by capability or loose name instead of hard-coding a serving endpoint id.

import { resolve } from "@dbx-tools/model";

const selected = await resolve.selectModel(client, host, {
  explicit: "claude sonnet",
  modelClass: "chat-balanced",
});

Run OpenAI-Shaped Tools Against Databricks

Use [@dbx-tools/appkit-model-gateway](/packages/appkit-model-gateway) when a local tool expects OpenAI-compatible endpoints with Databricks auth and Model Serving resolution.

dbx model-gateway --profile my-workspace --port 4000

Then point the client at http://127.0.0.1:4000/v1. The foreground command keeps the gateway loopback-only and resolves credentials through @dbx-tools/auth.

Authenticate With Databricks OAuth

Use [@dbx-tools/auth](/packages/auth) for direct PAT and M2M credentials, lazy CLI-backed U2M with automatic CLI login, App OBO/App SP authentication, secure token storage, and check-lock-recheck refresh. [@dbx-tools/cli/auth](/packages/cli) exposes the same runtime through dbx auth.

dbx auth login --profile my-workspace
dbx auth token --profile my-workspace
dbx auth status --profile my-workspace

Require Human Approval For Email

Use [@dbx-tools/email](/packages/email) with [@dbx-tools/ui/email](/packages/ui) when an agent should draft email but not send it until a user approves the suspended tool call.

import { email, emailTool } from "@dbx-tools/email";
import { mastra } from "@dbx-tools/appkit-mastra";

const agent = agents.createAgent({
  instructions: "Draft emails, then wait for approval before sending.",
  tools: () => ({ send_email: emailTool() }),
});

await createApp({
  plugins: [server(), lakebase(), email(), mastra({ agents: agent })],
});

Put A Gated Public URL In Front Of A Command

Use [@dbx-tools/tunnel](/packages/tunnel) inside an AppKit app, where the portr tunnel and the [@dbx-tools/auth-gate](/packages/auth-gate) passwordless gate run in-process through tunnelInterceptor() and the authGate plugin. The gate supports Better Auth email OTP recovery and passkeys with Lakebase or SQLite persistence.

Use [@dbx-tools/cli/tunnel](/packages/cli) when the process is not an AppKit app - a Python service, a static server, a third-party binary - and should still be reachable only by approved email addresses.

dbx tunnel --allow databricks.com -- bun src/server.ts
dbx tunnel status --allow databricks.com

The wrapper claims the public port, moves the wrapped command to a private one, and gates traffic in between. status prints the resolved configuration without starting anything.

Development

This repository uses a small internal workspace generator so package metadata, barrels, generated schemas, and examples stay consistent. That tooling is not the main product surface of the repo, but it is documented for contributors:

• [@dbx-tools/projen](https://github.com/reggie-db/dbx-tools/tree/main/projen) documents the projen engine, package discovery, generated files, mixins, and codegen.
• [dbx-tools](/packages/cli) documents the contributor CLI.

Useful contributor commands:

bun install
bunx projen
bun run --filter '*' compile
bun run --filter '*' test
bun run format
uv sync --all-packages
uv run pytest
uv run ruff check packages/py

Documentation

The READMEs are the current package-level source of truth. The GitHub Pages site is generated from those README files, so package docs are not maintained twice. See [docs/README.md](https://github.com/reggie-db/dbx-tools/blob/main/docs/README.md) for the local build command and Pages workflow.

Release Notes

Release notes can be found in docs/releases.