Build Your First Databricks App with Codex: A Practical Setup Guide

[epandya]

Build Your First Databricks App with Codex: A Practical Setup Guide

AI coding agents can help data practitioners move from an idea to a working application without spending days learning every detail of a new Python or JavaScript framework, deployment model, or API. The key is giving the agent the right development environment and a clear path to your data and AI platform.

This guide walks through how to connect OpenAI Codex CLI to Databricks, create a simple Databricks App, develop it locally, and deploy it to your workspace. It starts with the recommended ucode setup and then covers manual Codex configuration for teams that want more control.

By the end, you will have a repeatable workflow for using Codex as an AI pair programmer while keeping your application close to Databricks data, models, governance, and deployment services.

What you are building

Databricks Apps lets you build and deploy data and AI applications directly in your Databricks workspace. Apps run on managed serverless infrastructure and can integrate with services such as Unity Catalog, Lakebase, Databricks SQL, and OAuth-based authentication. You can use familiar frameworks including Streamlit, Dash, Gradio, React, and other Python or Node.js frameworks. Learn more in the Databricks Apps documentation.

For this walkthrough, the workflow looks like this:

• Use Codex to scaffold and modify application code.
• Use Databricks Apps as the deployment target.
• Use workspace-native services for data, AI, authentication, and governance.
• Iterate locally, then synchronize or deploy the tested application to Databricks.

You can use this pattern for turning dashboards into interactive apps, building data-entry tools, RAG applications, internal operational workflows, lightweight AI assistants and more. 

Prerequisites

Before you begin, make sure you have:

• Access to a Databricks workspace with Databricks Apps enabled.
• Unity Catalog enabled in the workspace.
• Permission to create and deploy apps.
• Run  databricks aitools skills install to install Databricks Apps skills (note: This should be executing after installing Codex) 
• Python 3.12 or later.
• uv, the Python package and tool manager used in the recommended setup.
• The Databricks CLI.
• Or OpenAI Codex CLI, if you plan to use the manual setup path.

Databricks Apps can be developed in an IDE such as Visual Studio Code, PyCharm, or IntelliJ IDEA. The Databricks Apps development guide contains the environment and application requirements.

Option 1: Set up Codex with ucode — the recommended path

ucode is Databricks’ command-line entry point for running supported coding agents through Unity AI Gateway. It can authenticate to your workspace and configure supported agents, including Codex CLI. It can also register Databricks MCP servers for capabilities such as Unity Catalog functions, AI Search, SQL warehouses, and discovered external connections.

1. Install ucode

Install ucode with uv:

uv tool install git+https://github.com/databricks/ucode

You can see the available commands with:

ucode --help

2. Start Codex through Databricks

Launch Codex with:

ucode codex

On first launch, ucode prompts you for your Databricks workspace URL, authenticates you, and writes the agent configuration. Later launches can go directly to Codex.

You can pass supported flags through to Codex. For example:

ucode codex --full-auto

Use approval settings carefully, especially when working with production repositories or applications. Start with a mode that lets you review changes before they are applied.

3. Add Databricks MCP servers when needed

MCP servers give Codex structured access to tools and services beyond the local filesystem. To configure Databricks MCP servers, run:

ucode mcp add

Add only the MCP servers your project needs. A smaller tool surface is often easier for an agent to use reliably and easier for you to govern.

For example, an app that queries a SQL warehouse may need SQL-related capabilities, while an app that uses governed search may need AI Search access. Keep the first iteration narrow, then add tools as the application requirements become clearer.

4. Choose a model

You can change the model from inside Codex with /model. If your workspace exposes approved open-source model services, ucode can also pass a model explicitly:

ucode codex --model <model-service-name>

Your available model services depend on workspace configuration and permissions.

Option 2: Configure Codex manually

The recommended ucode workflow is the simplest way to get started, but a manual configuration can be useful for teams that manage Codex settings centrally or want to inspect the configuration directly.

1. Install Codex CLI

Install Codex CLI version 0.118 or later:

npm install -g @openai/codex@latest

2. Authenticate to Databricks

Install the Databricks CLI, then authenticate to your workspace:

databricks auth login --host <workspace-url>

Replace <workspace-url> with the URL of your Databricks workspace. You only need to complete this login once for the local environment.

3. Configure ~/.codex/config.toml

Create or edit the Codex configuration file at ~/.codex/config.toml:

profile = "default"

[profiles.default]

model_provider = "Databricks"

[model_providers.Databricks]

name = "Databricks AI Gateway"

base_url = "<workspace-url>/ai-gateway/codex/v1"

wire_api = "responses"

[model_providers.Databricks.auth]

command = "sh"

args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]

timeout_ms = 5000

refresh_interval_ms = 1800000

Replace <workspace-url> in both places with your workspace URL. The configuration retrieves a short-lived Databricks token when Codex needs one and refreshes it during longer sessions.

Make sure jq is installed and available on your PATH. Then start Codex:

codex

You can change models from the Codex interface with /model.

For the full integration details, including model services, usage tracking, governance, and OpenTelemetry, see Integrate with coding agents.

[Manual] Create a starter Databricks App

The quickest way to understand the workflow is to start from a template. The Databricks Apps getting-started tutorial uses a simple Gradio application and then shows how to export, run, modify, and redeploy it.

In your Databricks workspace:

1. Open the app switcher and select Databricks Apps.
2. Select Create app.
3. Choose the Gradio Hello World template.
4. Give the app a name, such as codex-databricks-starter.
5. Create the app.

After the app is created, Databricks deploys it and provides a preview URL. The template includes the core files you need:

• app.py contains the application logic and user interface.
• app.yaml defines runtime settings, including the application entry point.
• requirements.txt lists Python dependencies.

At this stage, the goal is not to build the final product. The goal is to give Codex a working application that it can inspect, explain, and improve.

[Agent-first] Create a starter Databricks App

After you have installed the Databricks AI skills using the CLI, you can just prompt your agent to create an app. For instance, you could say: “Create an app that will display live data over from the X table in Unity Catalog and contains a side chat where users can ask questions through Genie”.

The agent will create a first version of your app. The framework used by default is AppKit, which was built specifically to create beautiful and functional apps on Databricks. You may learn about it on the Databricks Developers Getting Started page. If you’d like, you may also specifically prompt your agent to use a specific language or framework.

Once your app is scaffolded, you will be able to preview it locally, and request any new features or fixes to be done. The agent is able to handle the full development and deployment flow, including:

• Inspecting your Unity Catalog data to discover its schema and semantics, and display it using the right graphs. 
• Creating the necessary resources your app depends on, including Lakebase databases, Genie spaces, and AI endpoints.
• Creating your app, deploying it, and debugging any issues you may encounter.

Give Codex a useful first task

A coding agent works best when you provide a specific outcome, the constraints, and the definition of done. Instead of asking Codex to “make this app better,” try a prompt like this:

Inspect this Databricks App and explain its current structure.

Then update it to:

1. Add a text input for a SQL query.

2. Run the query through the configured Databricks SQL resource.

3. Display the results in a table.

4. Show a clear error message when the query fails.

5. Avoid logging credentials or sensitive query results.

6. Keep the existing startup command and make the app run locally.

Before changing files, describe the files you plan to modify.

After making changes, list the tests I should run.

This prompt gives Codex a bounded task, a security requirement, and a review checkpoint. For larger changes, ask Codex to create a plan first and implement the work in small increments.

Useful prompts for data practitioners include:

• “Explain this application as if I am comfortable with SQL but new to web development.”
• “Add a filter for date range and validate the input before submitting the query.”
• “Move this expensive transformation out of the request path and explain the recommended Databricks-native alternative.”
• “Review this app for least-privilege access and identify any credentials that should be removed.”
• “Add a loading state and a user-friendly error message without changing the data logic.”

The agent can write code, but you remain responsible for validating the query logic, access controls, data exposure, and production behavior.

Add Databricks resources deliberately

As your app becomes useful, connect it to the platform services it needs. Databricks Apps supports resources such as Databricks SQL, secrets, and Lakebase. The resources documentation explains how to configure these connections.

A good progression is:

1. Start with static or sample data.
2. Add one governed resource.
3. Test the app with realistic permissions.
4. Add authentication and authorization requirements.
5. Review logs, costs, and failure behavior.

For apps that need transactional state, Lakebase provides a managed Postgres backend that can be added as an app resource. See Using Lakebase with Databricks Apps for a database-backed application example.

Avoid placing tokens, passwords, or connection strings directly in source code. Use Databricks-managed authentication, app resources, and environment variables as appropriate. The authorization guide provides additional guidance for service principals, user authorization, and least-privilege access.

Deploy the application

When the app works locally, deploy it back to your Databricks workspace using the command shown in the app overview page. Databricks builds the application, installs its dependencies, and runs the command defined in app.yaml.

For a team workflow, store the application in Git and deploy from a repository. Git-based deployment gives you version control, pull-request review, collaboration, and a path to automated deployments. The Databricks Apps deployment guide covers workspace sync, Git deployment, and automatic deployment options.

Before deploying to a shared or production workspace, verify:

• The app listens on the host and port expected by Databricks Apps.
• Dependencies are pinned or managed with a reproducible lock file.
• The app requests only the permissions it needs.
• Secrets and tokens are not printed to logs.
• User input is validated and sanitized.
• Expensive work is moved to Databricks-native services where appropriate.
• Errors are handled without exposing stack traces or sensitive data.

The Databricks Apps best practices guide covers security, performance, networking, dependency management, logging, and graceful shutdown behavior.

A practical Codex operating model

For many teams, the most effective pattern is a short review loop:

• Ask Codex to inspect the repository and summarize the architecture.
• Ask for a plan before non-trivial changes.
• Make one focused change at a time.
• Run the app locally after each meaningful change.
• Review the diff, permissions, and data access.
• Deploy only after the application passes functional and security checks.

This approach makes Codex useful to people who may be new to application development without removing human judgment from the workflow.

Get started with your own app

The combination of Codex and Databricks Apps gives data practitioners a practical path from analysis to application. Codex helps translate intent into code, while Databricks provides the governed environment for data, AI, authentication, and deployment.

Start with a small app: a query explorer, a business intake form, a RAG prototype, or a model-powered workflow. Give Codex a narrow first task, test locally, connect only the resources you need, and promote the result through a reviewed deployment process.

That is the core loop: describe the outcome, inspect the generated work, test against real requirements, and iterate until the app is ready for its users.

Sources and further reading

• Integrate with coding agents
• Get started with Databricks Apps
• Develop apps
• Deploy a Databricks app
• Best practices for Databricks Apps
• Configure authorization in a Databricks app
• Databricks AppKit