Install
On this page
Three ways to run it. They are not a matter of taste: each exists because a different constraint makes the other two impossible.
OpenGenie is a Databricks App: one FastAPI process that serves the React front end and
starts an opencode agent and a fenced tool server for each conversation. All three paths
run the same code; they differ in who owns the process and what it can reach.
Which one is yours
As a Databricks App
The real deployment. The app runs in your workspace and acts as the signed-in user, so Unity Catalog permissions apply to the agent exactly as they apply to you.
On your machine
For development and for reading the code. Your CLI login stands in for single sign-on, so the app acts as you.
From a notebook only
The original study: an agent in the Databricks sandbox, driven from a notebook. No front end. The cheapest way to see whether the idea holds on your data.
A · As a Databricks App
1. Change what is specific to the author's workspace
The repository deploys the author's own instance, so a few values name his workspace. Change them before anything else. Both files are in apps/coding-agent/.
| Setting | Set it to |
|---|---|
APP_LLM_ADMINS in app.yaml | the e-mails allowed to edit the model catalogue for everyone. Empty means nobody. |
APP_DEFAULT_MODEL in app.yaml | a model your workspace can reach, e.g. databricks/databricks-llama-4-maverick |
LLM_VERTEX_PROJECT and APP_LLM_VERTEX_PROJECT in app.yaml | your Google Cloud project — or remove them, and the vertex-sa resource in databricks.yml, if you do not use Vertex |
APP_LLM_PG_ENDPOINT in app.yaml | your Lakebase endpoint (step 2) |
WS_SRC in the Makefile | the workspace folder the app deploys from, e.g. /Workspace/Users/you@company.com/coding-agent |
2. Create Lakebase and the encryption key
In production the app refuses to start without a durable journal, because a conversation that lives in container memory is lost on the next redeploy. Lakebase also holds the model catalogue and the encrypted provider keys.
# a Lakebase project for sessions, the model catalogue and stored keys
databricks postgres create-project coding-agent-llm \
--json '{"spec":{"display_name":"coding-agent-llm"}}'
# the key that encrypts stored provider keys:
# a Databricks secret, never in the database
databricks secrets create-scope coding-agent-llm
python3 -c "import os,base64
print(base64.urlsafe_b64encode(os.urandom(32)).decode())" \
| tr -d '\n' \
| databricks secrets put-secret coding-agent-llm llm-kek
The app's service principal then needs a Postgres role on that project; the exact commands are in the operations runbook.
3. Deploy, and check it is really your code
git clone https://github.com/raphaelmansuy/opengenie.git
cd opengenie
# create the app, its user scopes and its secret resources
databricks bundle deploy -t dev
# check the toolchain, the login, and what is deployed
make -C apps/coding-agent doctor
# sync the source, deploy, then verify the live URL serves this checkout
make -C apps/coding-agent deploy
make deploy ends by probing the live app, because “SUCCEEDED” from the platform means the process started, not that it is serving the code you just wrote. Run make -C apps/coding-agent for the other targets: status, url, logs, stop, start.
The bundle requests the user scopes the agent needs (SQL, files, model serving, AI Gateway, workspace, and read access to catalogues, schemas and tables). Requesting a scope is not granting it: grant them on the app if your workspace does not do so automatically.
On a trial workspace. App compute and model endpoints have daily quotas. When one is exhausted the error reads like a configuration problem. If a deploy fails with a message about a Git repository or a daily limit, check the quota first.
B · Locally, against your workspace
cd apps/coding-agent
make setup # venv, Python and npm dependencies
export DATABRICKS_HOST=https://YOUR-WORKSPACE.cloud.databricks.com
databricks auth login --host "$DATABRICKS_HOST"
make dev # http://127.0.0.1:8062, scripted agent
make dev-real # http://127.0.0.1:8071, real agent and model
Both take a fresh token from your databricks auth login session, so the workspace browser shows your real files. make dev replaces the model with a deterministic agent that plays scripted scenarios, which is how the interface is developed and tested; make dev-real runs the real opencode agent against a real model. Before you deploy, run make check (types and unit tests, no network).
The token is the boundary. Locally, the app acts as whoever owns the token. The fence limits what the agent asks for; the token limits what it may do. Point it at a workspace where your rights are what you would give an agent.
C · From a notebook only
This is the path in the tutorial, and it needs no local shell. Import one notebook, run its cells in order, and you have an agent that runs real SQL and a fence you can test by trying to break it. One person, one session, no interface beyond the notebook.
What none of the paths can do
| Not possible | Why |
|---|---|
| Run Python as you | Apps user authorisation has no compute scope. Python cells run on serverless as the app's service principal, only when an administrator starts them, and every result says where it ran. |
| Pick a cluster | The app runs SQL on a warehouse. A cluster picker for a choice it cannot honour would be a lie. |
| Schedule, comment or share | Those are workspace features. The app opens the same files, so do it in Databricks. |
| Inline completion | It needs a low-latency path the agent protocol does not have. |
| See what you cannot | The app acts as you. Its permissions are your permissions. |
After it runs
Test the fence first: ask the agent to write outside the folder you named, and read the refusal. Then read safety and governance for what the fence does not cover, and the decision guide if you are deciding whether to roll it out.
Uninstalling
databricks bundle destroy -t dev
The agent's working folders and any table it created stay where they are. They are your data, in your workspace, and a tool that deletes them on uninstall is a tool you cannot trust with them.