terrakernel/odxpilot repository overview

⁠ODXPilot

An AI assistant for day-to-day Odoo administration. People ask in plain language; ODXPilot reads Odoo to answer, and plans changes as proposals that a person approves on a plan card before anything is written. Nothing is ever deleted.

This image is the pilot part of an ODXPilot stack: the web UI and chat API (orchestrator) and the Odoo tools behind the role policy (odx-mcp). It runs together with terrakernel/odxproxy⁠ (the gateway to your Odoo), terrakernel/odxbrain⁠ and terrakernel/odxdocs⁠ (which Odoo model answers a question, which of your SOPs covers a task).

⁠Quick start

The installer asks a few questions, sets up the whole stack with Docker Compose and checks it end to end:

curl -fsSL https://raw.githubusercontent.com/terrakernel/odxpilot-install/main/install.sh | bash

To read it first: curl -fsSL <that url> -o install.sh; less install.sh; bash install.sh. bash install.sh --help lists the options, including unattended installs. Source of the installer and the Compose bundle: https://github.com/terrakernel/odxpilot-install⁠

Then open http://127.0.0.1:8700/⁠ and ask, for example, "Which customer invoices are still unpaid?"

⁠What you need

• Docker with Compose 2.20 or newer, on Linux or macOS (Windows: WSL 2).
• An Odoo instance (its URL and database) and an Odoo user for ODXPilot with an API key. Use a test database first: approved proposals do write to it.
• ODXProxy (the proxy part) with its licence (license.json, from https://odxproxy.io⁠).
• An LLM: an OpenAI, Anthropic or Google Vertex AI key, or your own OpenAI-compatible endpoint (local inference). Questions, the Odoo data the role may read (masked fields stay masked) and attached files go to that LLM.

⁠How it works

browser ──► orchestrator ──► odx-mcp ──► ODXProxy ──► your Odoo
              │                 └──► ODXBrain / odxdocs (models, SOPs)
              └──► the LLM you choose

• One stack, one Odoo instance. The instance URL and database are fixed in the config; odx-mcp refuses any other.
• Default deny. Every tool call is checked against the role's policy (YAML, model by model); the LLM is never the enforcement point. Sensitive fields can be masked before they reach it.
• Changes need an SOP and an approval. ODXPilot proposes a create, an edit or an action only when one of your SOPs covers the task; each shows as a plan card, and nothing is written until a person presses Approve. Apply re-checks the live schema and refuses records that changed since.
• Odoo API keys stay on the server side: never in the browser, a prompt or a tool result.
• Files in the chat: CSV, Excel and JSON tables can be read, summed and compared with Odoo; answers can be exported to Excel.

⁠Using the image

One image runs both services; the command picks which:

• Settings come from a mounted odxpilot.toml at /etc/odxpilot/odxpilot.toml (ODXPILOT_CONFIG); role policies at /etc/odxpilot/policies; uploads at /srv/odxpilot/uploads (writable for the orchestrator, read-only for odx-mcp).
• No secrets in the image or the config file. Keys come from the environment or secret files (the config names them as { env = ... } / { file = ... }).
• Runtime: distroless (no shell, no package manager), runs as uid 65532, works with a read-only root filesystem and a tmpfs /tmp.
• Health: GET /health on either port.
• Checks: odxpilot-orchestrator check (the configured LLM streams, calls a tool, answers) and odx-mcp check (the role policies against the live Odoo).

The Compose bundle in the installer repo shows the complete wiring.

⁠Tags

• 0.1.0: first release.
• latest: the newest release. Pin a version in production; the installer's bundle pins tested combinations of all four images.

Platforms: linux/amd64, linux/arm64. Images carry SBOM and provenance attestations.

⁠Status

Early release, for trying ODXPilot on a test Odoo database. There is no sign-in yet: the web UI listens on loopback and whoever uses it acts as the one role set in the config. Between machines the parts talk plain HTTP with keys, so keep them on a private network or VPN, or put HTTPS in front.

More: https://odxproxy.io⁠