🚀 apx is the toolkit for building Databricks Apps ⚡

---

✨ apx bundles together a set of tools and libraries to help you with app development lifecycle: develop, build and deploy.

💡 The main idea of apx is to provide convenient, fast and AI-friendly development experience.

🚀 Quickstart

1. Run the command to initialize the project:

uvx git+https://github.com/databricks-solutions/apx.git init

2. Open the project in Cursor (or any IDE of your choice, for that matter), allow usage of apx and shadcn mcp
3. Start providing prompts to build an app, e.g.:

Use apx mcp server to start development server, then create a nice application for order management.
Use shadcn mcp to add new components, make sure style is consistent and data is properly fetched from the backend. Start with mocking the backend data (yet use pydantic models), then implement the actual backend.

4. Deploy whenever ready via Databricks CLI:

databricks bundle deploy -p <your-profile>

🛠️ Stack

apx is built on top of the following stack:

• 🐍 Python + FastAPI in the backend
• ⚛️ React + shadcn/ui in the frontend

🔌 To connect the frontend and the backend, apx uses orval to generate the client code from the OpenAPI schema.

🚀 Init

To kickstart your app, please make sure you have:

• ✅ uv installed
• ✅ bun installed
• ✅ git installed

Then you can use the following command:

uvx git+https://github.com/databricks-solutions/apx.git init

This will launch an interactive prompt that will guide you through:

• 📝 Naming your app (or using a randomly generated name)
• 🔧 Selecting a Databricks profile (if you have any configured)
• 🤖 Setting up AI assistant rules (cursor/vscode/codex/claude)

The app will be created in the current working directory by default. You can specify a different path via:

uvx git+https://github.com/databricks-solutions/apx.git init /path/to/your/app

⚙️ Non-Interactive Mode

You can also specify all options via command-line flags to skip the prompts:

uvx https://github.com/databricks-solutions/apx.git init \
  --name my-app \
  --template essential \
  --profile my-profile \
  --assistant cursor \
  my-app

This will create a new app in the my-app directory with the app name my-app.

📁 Project Structure

The project structure is as follows:

my-app
├── package.json
├── pyproject.toml
├── README.md
├── src
│   └── sample
│       ├── __dist__
│       ├── backend
│       │   ├── app.py
│       │   ├── config.py
│       │   ├── dependencies.py
│       │   ├── models.py
│       │   ├── router.py
│       │   ├── runtime.py
│       │   └── utils.py
│       └── ui
│           ├── components
│           ├── lib
│           ├── routes
│           ├── main.tsx

📦 The __dist__ directory is the directory where the frontend bundle is stored, so it can be served by the backend.

📚 Databricks SDK Documentation

The Databricks SDK documentation is available via MCP server. You can search for methods and models using the following command:

uv run apx mcp sdk search <query>

This will return a list of methods and models that match the query.

⬆️ Upgrading apx

To upgrade apx, you can use the following command:

uv sync --upgrade-package apx

This will pull the latest changes from the main branch and update the apx package.

🎮 Commands

🚀 init

uvx git+https://github.com/databricks-solutions/apx.git init [APP_PATH]

Initializes a new app project with interactive prompts for configuration. Supports optional flags to skip prompts:

Arguments:

• APP_PATH: The path to the app (optional, defaults to current working directory)

Options:

• --name, -n: Specify the app name
• --template, -t: Choose a template (essential/stateful)
  • 🎯 Essential template is a basic template with UI and API.
  • 💾 Stateful template also includes Lakebase integration via sqlmodel.
• --profile, -p: Specify a Databricks profile
• --assistant, -a: Choose AI assistant rules (cursor/vscode/codex/claude)
• --layout, -l: Choose the layout (basic/sidebar)
• --skip-frontend-dependencies: Skip installing frontend dependencies (bun packages)
• --skip-backend-dependencies: Skip installing backend dependencies (uv sync)
• --skip-build: Skip building the project after initialization

🔥 dev - Development Server Management

The dev command group manages development servers in detached mode:

Start Development Servers

uv run apx dev start [APP_DIR] [OPTIONS]

Starts backend, frontend, and OpenAPI watcher in detached mode.

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

Options:

• --host: Host for dev, frontend, and backend servers (default: localhost)
• --api-prefix: URL prefix for API routes (default: /api)
• --obo/--no-obo: Enable/disable On-Behalf-Of header (default: enabled)
• --openapi/--no-openapi: Enable/disable OpenAPI watcher (default: enabled)
• --max-retries: Maximum number of retry attempts for processes (default: 10)
• --watch, -w: Start servers and tail logs until Ctrl+C, then stop all servers

Check Server Status

uv run apx dev status [APP_DIR]

Shows status of all running development servers (backend, frontend, OpenAPI watcher).

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

View Logs

uv run apx dev logs [APP_DIR] [OPTIONS]

Displays historical logs from development servers.

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

Options:

• --duration, -d: Show logs from last N seconds
• --follow, -f: Follow log output (like tail -f). Streams new logs continuously.
• --ui: Show only frontend logs
• --backend: Show only backend logs
• --openapi: Show only OpenAPI logs
• --app: Show only application logs (from your app code)
• --system: Show only system logs from the apx dev server
• --raw: Show raw log output without prefix formatting

Restart Development Servers

uv run apx dev restart [APP_DIR]

Restarts all running development servers, attempting to reuse the same ports.

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

Stop Development Servers

uv run apx dev stop [APP_DIR]

Stops all running development servers.

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

Check Project Code

uv run apx dev check [APP_DIR]

Checks the project code for errors using TypeScript compiler and basedpyright.

Arguments:

• APP_DIR: The path to the app (optional, defaults to current working directory)

MCP Server

uv run apx dev mcp

Starts MCP server that provides tools for managing development servers. The MCP server runs over stdio and provides tools for start, restart, stop, status, and get_metadata operations.

Apply Addon

uv run apx dev apply <addon_name> [OPTIONS]

Applies an addon to an existing project. This command can be used to add new features, integrations, or templates.

Arguments:

• addon_name: The addon to apply (required). Available addons: essential, stateful, cursor, vscode, codex, claude, sidebar

Options:

• --app-dir: The path to the app (defaults to current working directory)
• --force, -f: Apply addon without prompting for confirmation when files would be overwritten
• --file: Apply a single file from the template (path relative to template root). When using this option, you can also use 'base' or 'essential' as the addon_name to apply files from the base template

Examples:

Apply the entire sidebar addon:

uv run apx dev apply sidebar

Apply a single file from the essential template:

uv run apx dev apply essential --file vite.config.ts

Force apply an addon without confirmation:

uv run apx dev apply stateful --force

📦 build

uv run apx build [APP_PATH] [OPTIONS]

Prepares the app for deployment by building both frontend assets and Python wheel.

Arguments:

• APP_PATH: The path to the app (optional, defaults to current working directory)

Options:

• --build-path: Path to the build directory where artifacts will be placed, relative to the app path (default: .build)
• --skip-ui-build: Skip the UI build step

🔧 openapi

uv run apx openapi [APP_PATH] [OPTIONS]

Manually generates OpenAPI schema and orval client.

Arguments:

• APP_PATH: The path to the app (optional, defaults to current working directory)

Options:

• --watch, -w: Watch for changes and regenerate automatically
• --force, -f: Force regeneration even if schema hasn't changed

Note: you don't need to run this command manually, the watcher will run automatically when you start the development server.

📝 shadcn directory repositories

When the project is initialized, the following directories are added to the shadcn directory (via repositories key in the components.json file):

• https://animate-ui.com/ - for animations. MIT License.
• https://ai-sdk.dev/ - for AI components (e.g. chat and prompts). Apache-2.0 License.
• https://svgl.app/docs/shadcn-ui - various SVG icons. MIT License.

We've carefully selected these repositories to ensure that the components are of high quality and are well-maintained.

If you don't want to use these repositories, you can remove them from the components.json file.

🔧 Troubleshooting

Missing apxPlugin in vite.config.ts

If your vite.config.ts doesn't have a mention of apxPlugin, you should apply the essential template file:

uv run apx dev apply essential --file vite.config.ts

This will update your vite configuration with the required apx plugin that handles the development server integration.

📜 Project todos

• MCP of apx commands
• Add chat template
• Add a way to add a custom template

License and Third Party Libraries

License

© 2025 Databricks, Inc. All rights reserved. The source in this project is provided subject to the Databricks License.

Third Party Libraries

library	description	license	source
FastAPI	High-performance API framework based on Starlette	MIT	GitHub
Pydantic	Data validation and settings management using Python type hints	MIT	GitHub
SQLModel	SQLAlchemy-like ORM for Python	MIT	GitHub
Databricks SDK for Python	Official Databricks SDK for Python	Apache-2.0	GitHub
orval	OpenAPI client generator	MIT	GitHub
shadcn/ui	UI library for React	MIT	GitHub
React	Library for building user interfaces	MIT	GitHub
TypeScript	Programming language for web development	Apache-2.0	GitHub
Bun	JavaScript runtime	MIT	GitHub
uv	Fast, modern Python package manager	MIT	GitHub
jinja2	Template engine for Python	MIT	GitHub
rich	CLI interface library for Python	MIT	GitHub
typer	Typer is a library for building CLI applications	MIT	GitHub
uvicorn	ASGI server for Python	BSD-3-Clause	GitHub
httpx	HTTP client for Python	BSD-3-Clause	GitHub
watchfiles	File change monitoring for Python	MIT	GitHub
hatchling	Build backend for Python	MIT	GitHub
uv-dynamic-versioning	Dynamic versioning for Python packages	MIT	GitHub
vite	Frontend build tool for JavaScript	MIT	GitHub
tailwindcss	Utility-first CSS framework for rapid UI development	MIT	GitHub
smol-toml	Tom's Obvious, Minimal Language for JS	MIT	GitHub
psutil	Cross-platform library for retrieving information on running processes and system utilization (CPU, memory, disks, network) in Python.	BSD-3-Clause	GitHub