Bridge module

Odoo / Bridge Module

Speak To Your Database Odoo Bridge

The Speak To Your Database Odoo Bridge is one of two ways to connect Odoo (the other is an Odoo API key) for Odoo 15 through 19. It is a lightweight Odoo module that gives Speak To Your Database a controlled, read-only path into Odoo through the Odoo ORM, so answers can be planned, validated, and explained against trusted Odoo metadata.

It gives Speak To Your Database a controlled, read-only Odoo ORM path.
It does not write, create, update, or delete records.
It does not send SQL to Odoo.
It does not expose your database credentials.
It is published on Odoo Apps for Odoo 15, 16, 17, 18 and 19. Install the version that matches your Odoo.

Open the module on the Odoo Apps marketplace. The technical module name is styd_odoo_bridge.

The bridge is a trust anchor, not a business interface inside Odoo. It exposes safe, read-only metadata so the platform can plan, validate, and explain Odoo answers more safely. It never edits your data and never adds a new interface inside Odoo.

Choose your setup path

The bridge works on every supported Odoo major version, 15 to 19. Whether you can use it depends on your hosting, not on your Odoo version. An Odoo API key is the other way to connect, and it works on every hosting.

Path A. Odoo 15 to 19 (self-hosted, on-premise, Odoo.sh)

Install the Odoo Bridge module from the Odoo Apps marketplace, choosing the version that matches your Odoo.
Configure the bridge inside Odoo.
Connect it in Speak To Your Database under Settings → Connections (New connection → Odoo Bridge).

Path B. Odoo Online

The bridge module cannot be installed, because Odoo Online does not allow custom Python modules.
Connect with an Odoo API key instead: it works on Odoo Online (Odoo 15 and later). If Odoo blocks external access on your plan, we’ll tell you clearly.
A direct database connection is usually not available on Odoo Online.

Path C. Module installation not possible

Some managed environments do not allow installing any module, on any Odoo version.
In that case use a secured direct PostgreSQL / database connection under Settings → Connections.
Use read-only database credentials and network restrictions.
This is a fallback. See Direct database connection.

What the bridge does

The bridge lets Speak To Your Database retrieve trusted, read-only metadata directly from Odoo. This metadata improves security scoping, company-scope enforcement, model selection, field understanding, and answer confidence.

Detect the Odoo instance, version, edition, and installed modules.
Read the connector owner identity and company scope.
Expose allowed companies, default company, and active company metadata.
Expose groups, readable models, and model access information.
Expose field labels, types, relations, stored/computed flags, and selection values.
Help the planner choose safer execution paths and explain which scope was used.

What the bridge does not do

It does not add a new business interface inside Odoo.
It does not let Speak To Your Database edit, create, delete, or mutate Odoo records.
It does not send SQL to Odoo.
It does not expose uncontrolled raw business data or your database credentials.
It does not give invited workspace members automatic access to everything the connector owner can access.

Supported Odoo versions

The bridge module is published and production-ready for Odoo 15, 16, 17, 18 and 19. Odoo Apps listings are version-scoped, so open the page for your own Odoo major version, the links below go straight to it.

Odoo version	Recommended setup	Status
19.0	Odoo Bridge module on Odoo Apps	Production-ready
18.0	Odoo Bridge module on Odoo Apps	Production-ready
17.0	Odoo Bridge module on Odoo Apps	Production-ready
16.0	Odoo Bridge module on Odoo Apps	Production-ready
15.0	Odoo Bridge module on Odoo Apps	Production-ready

Install the module version that matches your Odoo. An Odoo module built for one major version does not run on another, and the Odoo Apps page has a version selector for exactly that reason. If you are unsure which version you run, check Settings → About inside Odoo.

Supported deployment types

Supported (Odoo 15–19)

Self-hosted Odoo
On-premise Odoo
Odoo.sh

Not supported for the bridge

Odoo Online, because custom Python modules cannot be installed there.
An Odoo reachable only over plain http, or only on a private or local network (LAN, VPN, localhost).

The Odoo base URL must be a public HTTPS address. Speak To Your Database refuses plain http:// URLs and hosts that are private or local, localhost, 10.x, 172.16–31.x, 192.168.x, link-local addresses and .local / .internal names, and it follows redirects only on the same host (for example http → https). A self-hosted or on-premise Odoo must be published on a public HTTPS domain (for example behind a reverse proxy) before you connect it.

Path A · Step 1. Install the bridge module (Odoo 15–19)

Install the Speak To Your Database Odoo Bridge from the Odoo Apps marketplace, selecting the version that matches your Odoo, then activate it from your Odoo Apps screen. The technical module name is styd_odoo_bridge.

Self-hosted / on-premise or Odoo.sh: if you install the module files directly instead of from the marketplace, place the styd_odoo_bridge module folder inside a custom addons directory and make sure that directory is on Odoo's addons_path. Copy the folder for YOUR Odoo major version (15.0 … 19.0).

# Get the module
git clone https://github.com/silkflo/odoo-bridge.git

# Copy the styd_odoo_bridge folder for YOUR Odoo version (e.g. 17.0)
sudo mkdir -p /opt/odoo/custom-addons
sudo rm -rf /opt/odoo/custom-addons/styd_odoo_bridge
sudo cp -r ./odoo-bridge/17.0/styd_odoo_bridge /opt/odoo/custom-addons/styd_odoo_bridge

The copied folder should contain __manifest__.py and __init__.py at its top level.

Add the custom addons path

Add the parent folder to addons_path in your Odoo configuration file (commonly /etc/odoo/odoo.conf):

addons_path = /usr/lib/python3/dist-packages/odoo/addons,/opt/odoo/custom-addons

Point addons_path at the parent folder /opt/odoo/custom-addons, not directly at /opt/odoo/custom-addons/styd_odoo_bridge.

Docker note: the custom addons folder must be visible inside the Odoo container, and the container-side path must be listed in addons_path. Mount the host folder or bake it into the image, changes made only inside a temporary container filesystem are lost on recreation.

Restart and install

sudo systemctl restart odoo.service

In Odoo, enable developer mode, open Apps, click Update Apps List, search for styd_odoo_bridge, then activate the module. CLI installation is also possible:

sudo -u odoo /usr/bin/python3 /usr/bin/odoo --config /etc/odoo/odoo.conf -d YOUR_DATABASE -i styd_odoo_bridge --stop-after-init
sudo systemctl restart odoo.service

On Odoo.sh, add the module to your repository, push the branch, let Odoo.sh build, then activate the module from the Apps screen.

Path A · Step 2. Configure the bridge in Odoo

After the module is installed, configure the bridge inside Odoo:

In Odoo, open Speak To Your Database → Connection Setup.
Enable the bridge and choose a connector owner.
Click Generate Token (or Rotate Token if you are replacing an existing one).
Copy the token shown, it is displayed only once.

Token handling: the raw token is shown once and is stored hashed in Odoo. Do not paste it into logs, screenshots, or client-side code. If you lose it, rotate the token and update it in Speak To Your Database.

Path A · Step 3. Connect in Speak To Your Database

Connect the bridge from your workspace:

Open Settings → Connections and choose New connection → Odoo Bridge.
Give the connection a name (for example, Odoo Production).
Paste the Odoo base URL, a public HTTPS address such as https://odoo.example.com. Plain http and private or local network addresses are refused (see the URL requirements).
Paste the bridge token you generated in Odoo.
Click Test connection, then Save connection.

Odoo Bridge connections live alongside your database connections on the Connections page. You can rename them, re-test them, or rotate the bridge token there at any time; each connection’s card also shows its sync status and data guide. Members are mapped to their Odoo users in Settings → Members → Odoo access.

After a successful connection, Speak To Your Database can display or store:

Bridge status and connector owner.
Available Odoo users, company labels, and company scope.
A user rights summary.
Odoo model and field metadata used by the planner.

If the connection does not succeed, verify the bridge health endpoint, token, database name, and Odoo base URL.

Optional. Verify the bridge endpoints

The examples below use http://127.0.0.1:8069 because they are meant to be run on the Odoo server itself for local verification. Speak To Your Database itself only connects to the public HTTPS base URL of your Odoo. If your Odoo server hosts multiple databases, include the X-Odoo-Database header.

curl -H "Authorization: Bearer YOUR_REAL_TOKEN" \
  -H "X-Odoo-Database: YOUR_DATABASE" \
  http://127.0.0.1:8069/styd_bridge/v1/health

A healthy response confirms the bridge is enabled and reachable, for example:

{
  "ok": true,
  "bridge_version": "0.2.0",
  "odoo_series": "19.0",
  "edition": "community",
  "server_time_utc": "..."
}

Exact values vary by Odoo version and bridge release. The same token is required for every endpoint listed under Reference.

Direct database connection (fallback)

The bridge is available for every supported Odoo major version, so a direct database connection is a fallback, not a version workaround. Use it only when no module can be installed in your Odoo at all, then connect through a secured direct database connection in Settings → Connections.

Use a dedicated, read-only database user.
Restrict network access: allow only STYD’s addresses (109.123.235.222 and 2407:3640:2324:5796::1), or use a read replica.
The database must be reachable at a public address: localhost and private network addresses are refused, and there is no SSH tunnel option.
Do not use the Odoo application superuser or broad admin database credentials.

Uncontrolled database access is risky; a secured read-only connection is an acceptable fallback when the bridge is not available. This path does not reproduce exact Odoo per-user permissions. Access is controlled by the database user's permissions and by Speak To Your Database workspace restrictions, not by Odoo record rules.

Workspace admins can further reduce what users and the AI can access by hiding tables for specific users in the AI Guide. For setup details, see Connections and Read-only database users.

Security model & access scope

There are two layers. The module limits what any read can reach. Speak To Your Database then narrows each read to the member who asks.

What the module does

It reads with its own access, limited to the companies of the user who generated the token. It does not apply each Odoo user's access rights or record rules.
It serves only a list of business models, and never users, access rules, settings, attachments, messages or HR data.
The token is stored hashed in Odoo and checked on every request. Each request is logged with its source address and a fingerprint of the token, never the token itself.

What Speak To Your Database adds for each member

A member must be mapped to an Odoo user. A member who is not mapped gets no Odoo data.
The mapped user's groups decide the areas the member can ask about: Accounting, Sales, Purchase and Inventory. Contacts and products are open to every mapped member.
The mapped user's companies are added as a filter to every read of a model that has a company. A mapped user without a company is refused.
These limits come from the last sync, so re-sync after changing users, groups or companies in Odoo.

Odoo record rules and per-user model access are not reproduced on a Bridge connection. Do not rely on it for row-level restrictions.
The company filter and the four areas are a coarse subset of what Odoo itself enforces. For an Odoo user whose rights Odoo must enforce in full, connect with an API key for that user instead.
Table hiding in Speak To Your Database does not apply to a Bridge connection, because it reads Odoo models, not tables.

For a direct database connection (the fallback path), the effective access is determined by the database user's permissions intersected with workspace restrictions, as described above.

Reference

Odoo Apps listings

One published listing per supported Odoo major version:

Repository

The bridge module is maintained in a dedicated GitHub repository:

https://github.com/silkflo/odoo-bridge

Technical module name

styd_odoo_bridge

Bridge endpoints

The bridge exposes these read-only routes:

/styd_bridge/v1/health
/styd_bridge/v1/security/snapshot
/styd_bridge/v1/users/directory
/styd_bridge/v1/users/search
/styd_bridge/v1/capabilities
/styd_bridge/v1/models
/styd_bridge/v1/models/<model>/fields
/styd_bridge/v1/search-read
/styd_bridge/v1/read-group

Every endpoint requires a valid bridge token sent as Authorization: Bearer YOUR_REAL_TOKEN. For multi-database Odoo servers, include the X-Odoo-Database header. Use HTTPS in production and keep the bridge token secret, never expose it in browser-side code, public logs, screenshots, or client-side JavaScript.

Upgrade the module

When the bridge module code changes, update the module on the Odoo server:

sudo -u odoo /usr/bin/python3 /usr/bin/odoo --config /etc/odoo/odoo.conf -d YOUR_DATABASE -u styd_odoo_bridge --stop-after-init
sudo systemctl restart odoo.service

On Odoo.sh, commit the updated module code, push the branch, let Odoo.sh rebuild, and upgrade the module from Apps if required.

Troubleshooting

The module does not appear in Apps

Confirm the module folder is inside a loaded custom addons directory.
Confirm the folder is named exactly styd_odoo_bridge.
Confirm the folder contains __manifest__.py and __init__.py.
Confirm addons_path points to the parent addons folder.
Restart Odoo, enable developer mode, and click Update Apps List.
Remove filters such as Official Apps and search again.

The bridge endpoint returns bridge_disabled

Confirm the module is installed.
Open Speak To Your Database → Connection Setup in Odoo.
Enable the bridge, choose the connector owner, and generate a token.
Save the configuration.

Health check returns unauthorized

Confirm the bridge is enabled in Odoo.
Confirm the token is sent as Authorization: Bearer YOUR_REAL_TOKEN and matches the token saved in Speak To Your Database. If unsure, rotate the token and re-enter it.

Multi-database Odoo cannot find the database

Send the X-Odoo-Database header.
Confirm the database name exactly matches the Odoo database name.

Test connection says the URL must be a public HTTPS address

Enter the https:// address of your Odoo, not http://.
Use a public domain name, not localhost, an address on your local network, or a .local name.
Publish a self-hosted or on-premise Odoo on a public HTTPS domain (for example behind a reverse proxy), then Test again.

Test connection fails in Speak To Your Database

Verify the Odoo base URL is a public HTTPS address reachable from the internet.
Verify the bridge token and the database header if required.
Run the /styd_bridge/v1/health endpoint manually with curl.
After it responds correctly, click Test connection, then Save connection again.

Help with the Bridge setup

If the installation is blocking you, we can walk through it with you: your addons path, the token setup and the endpoint checks, so you finish with a working bridge and a confirmed access scope.

If you would like us to walk through it on your environment, or if you are stuck on addons_path, the token, or the bridge endpoints, get in touch.