Local deployment (sandbox and container)¶

New in v1.6.0

An API key for the plugin on Odoo 14.0 to 19.0: sandbox up has Odoo create an API key for the admin user and keeps it in the .env as ODOO_API_KEY, never printed. It goes in the plugin's Odoo API key option, with Odoo password left empty. See Connect the plugin to the sandbox.
Fixed, a sandbox that never started: about one new sandbox in 64 got a database password that starts with "-", which the Odoo image of 11.0 and later read as an option. Generated passwords no longer start with "-". Only a sandbox of Odoo 11.0 or later that never started with such a password tells you to run sandbox destroy --yes, then sandbox up, and nothing is lost. One on 10.0, or one that already worked, stays as it is. See Troubleshooting.
The container mode image is ghcr.io/transgenia/odoo-mcp-tools:1.6.0.

New in v1.5.1

The container mode image is ghcr.io/transgenia/odoo-mcp-tools:1.5.1.
Container mode creates the marker ${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode, so the plugin's session-start hook stays silent while you use the container server.

New in v1.5.0

The container mode image is ghcr.io/transgenia/odoo-mcp-tools:1.5.0.
The container mode's odoo.env file can set the permission profile (ODOO_POLICY, standard by default), a policy file (ODOO_POLICY_FILE) and the audit folder (ODOO_AUDIT_DIR). See Permission policy.
In the sandbox, the delete exercise and the Studio-style changes need a profile other than standard: full to delete, builder for fields, views and automations.

New in v1.4.1

The container mode image is ghcr.io/transgenia/odoo-mcp-tools:1.4.1. Container mode is for Claude Code without Python.

New in v1.4.0

The sandbox covers Odoo Community 10.0 to 19.0 (was 16.0 to 19.0), each series with a PostgreSQL version it supports.

New in v1.3.0

/odoo-tools:deploy-local starts local infrastructure provided by Transgenia. It runs only when you invoke it and confirm: no hook runs Docker on its own.

You usually reach it from the guided route /odoo-tools:odoo-setup-mcp (phase 1, "I have no Odoo to practice with" or "I can't install Python"). The command also works on its own.

Requirements¶

Docker with Compose v2 (docker compose; the legacy docker-compose binary is not supported): Docker Desktop (Windows/macOS) or Docker Engine + the compose plugin (Linux). See docs.docker.com/get-docker.
For the sandbox: python3 3.9+ (the one the plugin already needs) and ~2 GB of disk.

Mode A: local Odoo sandbox¶

Odoo Community (CE) only

The sandbox is Odoo Community. Transgenia cannot provide Odoo Enterprise instances (licensed per subscription by Odoo S.A.) or Odoo Online ones (Odoo S.A.'s SaaS at odoo.com). To use them, connect your own Enterprise instance or Online database. On Online, the plan must include external API access: without it the connection fails even with correct credentials (see Troubleshooting).

Starts PostgreSQL + Odoo Community 10.0 to 19.0 on your machine, with a ready database (demo data optional), to practice without touching production.

Odoo 10.0 to 16.0: testing and migrations only

Odoo S.A. maintains only the three latest series (17.0, 18.0 and 19.0); 10.0 to 16.0 no longer receive security fixes. Official images up to 15.0 are amd64-only: Docker Desktop (Apple Silicon, Windows ARM) emulates them, slower; with Docker Engine on ARM Linux, register amd64 emulation first (binfmt/QEMU, e.g. docker run --privileged --rm tonistiigi/binfmt --install amd64) or the container fails with "exec format error". Each series uses a PostgreSQL version it supports:

Odoo	PostgreSQL
10.0, 11.0	10
12.0, 13.0	12
14.0, 15.0	13
16.0 to 19.0	16

Every week a workflow starts all ten series and checks them through the plugin's MCP server, which signs in as described below: with the API key on 14.0 to 19.0 (over JSON-2 on 19.0) and with the password on 10.0 to 13.0.

The command asks, one thing at a time: Odoo version (18.0 recommended), demo data, language (e.g. en_US) and port (8069 by default). Then it runs:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox up --odoo 18.0 --lang en_US --port 8069

What it does, in order:

Writes docker-compose.yml, odoo.conf and .env in ~/.odoo-tools/sandbox (folder 0700, .env 0600). The passwords (PostgreSQL, Odoo master and the admin user) are generated locally and never printed; since v1.6.0 none starts with "-", which the Odoo image of 11.0 and later read as an option.
Pulls the images from ghcr.io/transgenia/odoo and ghcr.io/transgenia/postgres: unchanged copies of the official images, refreshed weekly by Transgenia. If that registry does not answer, it uses the official Docker Hub images.
Starts the containers with Odoo published on 127.0.0.1 only.
Creates the database (sandbox by default) and checks the login.
On Odoo 14.0 and newer, has Odoo create an API key for the admin user, through odoo shell in a one-off container of the sandbox and Odoo's own res.users.apikeys. It checks that the key signs in and keeps it in the same .env as ODOO_API_KEY, never printed. Odoo lists it as "odoo-tools sandbox" under Preferences > Account Security. Later runs reuse it, or replace it if it was removed in Odoo. Odoo 10.0 to 13.0 have no API keys and keep the password, and so does a sandbox where the key could not be made: the script says why, and the next sandbox up tries again.

At the end it shows the URL, database, login and where the password (ODOO_ADMIN_PASSWORD in ~/.odoo-tools/sandbox/.env) and, on 14.0 and newer, the API key (ODOO_API_KEY in the same file) are; its plugin_credential field says which credential goes in the plugin options. Open the file yourself in your editor: Claude does not read it or copy the password or the key. Never paste the key or the password in the chat.

Connect the plugin to the sandbox¶

/plugin → odoo-tools → Configure options:

Option	Value
Odoo URL	`http://localhost:8069` (or the port you chose)
Odoo database	`sandbox`
Odoo login	`admin`
Odoo API key	Odoo 14.0 to 19.0: the value of `ODOO_API_KEY` from the `.env`. Empty on 10.0 to 13.0
Odoo password (Odoo < 14 only)	Odoo 10.0 to 13.0: the value of `ODOO_ADMIN_PASSWORD`. Empty on 14.0 to 19.0

If the summary says the sandbox has no API key (api_key starts with none:), use the password as on 10.0 to 13.0: on the sandbox it works in the Odoo password field too, although its title says Odoo < 14 only. The reason is in that same summary, and the next sandbox up tries to create the key again.

Restart Claude and verify with odoo_version. The plugin options are a single connection: to go back to production, enter the production values again.

In the sandbox you can use the Permission profile builder to practice fields, views and automations, or full to practice deletes. The plugin's example docs/policy-examples/sandbox-builder.json (profile builder) also opens deletes and test users. When you go back to production, set the profile back to standard (or readonly). See Examples.

Manage the sandbox¶

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox status
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox down           # stop, keep data
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox up             # start again; on 14.0+ creates the API key if missing
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox logs
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/deploy_local.py" sandbox destroy --yes  # deletes database and files

You can also ask in plain language: /odoo-tools:deploy-local status.

Changing the Odoo version

A database created with Odoo 18 cannot be opened by Odoo 17 (or the other way round). The script detects it and stops: run destroy --yes first, or use another folder with --dir.

Mode B: MCP server as a container¶

For machines with Claude Code without Python 3.9+. It is the same MCP server, packaged by Transgenia as a Docker image (amd64 and arm64), connected to your existing Odoo:

docker pull ghcr.io/transgenia/odoo-mcp-tools:1.6.0

The command creates ~/.odoo-tools/mcp/odoo.env (your user only) with placeholders; you fill in URL, database, login and API key in your editor. The file also carries, commented out, the permission policy and audit lines:
```
# ODOO_READONLY=1            # recommended for first steps
# ODOO_POLICY=standard       # permission profile: readonly, standard, builder or full
# ODOO_POLICY_FILE=/policy/policy.json   # optional, mounted read-only
# ODOO_AUDIT_DIR=/audit      # without it the audit lines go to docker logs
```
The profile defaults to standard (no deletes, no Studio-style changes, no secrets); full keeps the 1.4 behavior. With a policy file or an audit folder, add -v <absolute path of the policy file>:/policy/policy.json:ro and -v <absolute path of an audit folder>:/audit before the image name in the command of step 2.

Then mark the plugin's data folder as container mode. The marker tells the plugin's session-start hook that the container server is the one in use, so it stops reporting the plugin's own server, which stays unused, as never connected:
```
( umask 077; mkdir -p "${CLAUDE_PLUGIN_DATA}/diagnostics" && touch "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode" )
```

It registers it in Claude Code (showing you the command first):

claude mcp add odoo-tools-docker --scope user -- docker run -i --rm --env-file "$HOME/.odoo-tools/mcp/odoo.env" ghcr.io/transgenia/odoo-mcp-tools:1.6.0

Restart Claude and verify with odoo_version from the odoo-tools-docker server. If the plugin's own server is also configured, the tools show up twice: keep one. To undo this mode: claude mcp remove odoo-tools-docker and rm "${CLAUDE_PLUGIN_DATA}/diagnostics/container-mode".

On Windows the file is %USERPROFILE%\.odoo-tools\mcp\odoo.env; create it from your editor.

While the container-mode marker exists, the plugin's session-start hook shows no notice: the container server is the one in use, so the plugin's own server is expected to stay unused.

From sandbox to production¶

The sandbox is for learning and testing. To take Odoo + AI to production (hosting, security, migrations, integrations, training for your team), Transgenia provides assisted deployment and support through its official channels: dev@transgenia.org · WhatsApp +52 55 8034 0405. See Support.