docs/user_guide/sql-ai-shell.md
The Beekeeper Studio AI Shell is modelled after Claude Code and Aider. It is designed to increase the productivity of technical users (like you!).
The AI Shell embeds your agent right inside Beekeeper Studio. It has deep SQL awareness and the ability to explore schemas, understand relations and constraints, and write and execute SQL (with permission), right inside the app.
See our website for videos, screenshots, and more.
The AI Shell is included in all paid versions of Beekeeper Studio, with no additional charge. Note that you are responsible for the costs incurred with your AI provider, as Beekeeper does not act as a middle-man in any way.
All downloads of Beekeeper Studio come with a 14 day free trial, download Beekeeper Studio to try the AI Shell right now.
Your AI agent has access to the following tools from within Beekeeper Studio:
You can configure the AI Shell using the Beekeeper Studio configuration system.
{% ini-include section="plugins.bks-ai-shell" %}
You can provide custom instructions to personalize how the AI Shell responds to your messages. To add custom instructions:
Your instructions are appended to the AI Shell’s base instructions and are included with every message you send as a system prompt, ensuring consistent behavior across sessions. For details, see the instructions repository.
The AI shell is 100% optional. Even when in-use, no data is ever sent from the AI Shell to the Beekeeper Studio servers. The AI Shell communicates directly with your AI Agent of choice -- no middlemen.
To start using the AI Shell you must choose your agent and enter an API key. By doing so, you are permitting the Beekeeper Studio AI shell to communicate with your chosen AI agent.
The AI Shell allows your agent to explore your data's schema, run SQL, and read results. The AI Shell will show you what the AI sees as it is working, nothing is hidden from view.
The AI shell will send the following information to your agent when you use the shell:
The AI Shell can run SQL queries, then view the results of those queries. This is a key part of how the shell navigates around your database to figure things out.
There are some limited actions the AI shell can take without your permission, but it will always ask for your explicit consent when running SQL. This gives you the chance to review the code and reject it whenever you have concerns.
If you prefer not to be asked every time, you can enable Always allow execution of read-only queries:
You can disable the AI shell entirely by adding a flag to either your personal or administrator configuration file to disable the shell.
{% ini-include section="plugins.bks-ai-shell" %}
Even if the application user has previously entered an API key, this setting will disable the feature and lock out any further usage.
If AI Shell cannot connect to Ollama, it may be due to CORS restrictions. You’ll need to allow requests from Beekeeper Studio.
Run one of the following commands:
# Allow all origins
launchctl setenv OLLAMA_ORIGINS "*"
# Allow only Beekeeper Studio
launchctl setenv OLLAMA_ORIGINS "plugin://*"
Set an environment variable:
Press Windows + R, type sysdm.cpl, and press OK.
Go to Advanced > Environment Variables.
Add or edit the variable OLLAMA_ORIGINS.
Set the value to:
* (allow all origins), orplugin://* (only Beekeeper Studio).Edit the Ollama service config:
sudo systemctl edit ollama.service
Add the environment variable:
[Service]
Environment="OLLAMA_ORIGINS=*"
# or
Environment="OLLAMA_ORIGINS=plugin://*"
Then restart the service:
sudo systemctl restart ollama