Getting Started

This walkthrough takes you from nothing to a working search_read against a real Odoo database. It should take about ten minutes.

By the end you will have:

• ODXProxy running in Docker with a mounted config directory and a signed license,
• a verified /_/license and /_/about response,
• a first POST /api/odoo/execute call returning Odoo records.

Before you begin

You need four things:

Deploy the proxy

mkdir -p ~/odxproxy/config ~/odxproxy/logs

sudo chown -R 65532:65532 ~/odxproxy/logs

# Address and port for the proxy server to listen on
LISTEN_ADDR=0.0.0.0:6600

# The API key your gateway/clients must send as `x-api-key` on every /api/* request
PROXY_API_KEY=change-me-to-a-long-random-string

# Log level. `info` is the default; use `debug` while you are setting things up.
RUST_LOG=info,TheODXProxy=info

# Default timeout for the upstream Odoo call, in seconds.
# Overridable per request via the `x-request-timeout` header.
DEFAULT_ODOO_TIMEOUT_SECS=600

# Where rolling daily JSON logs are written (container path)
LOG_PATH=/var/log/odxproxy

# Path to the signed license file (container path)
LICENSE_KEY=/usr/share/odxproxy/config/license.json

# Clustering heartbeat — leave disabled unless you run multiple instances
HOSTNAME=YOUR_ODX_HOSTNAME_FOR_HEARTBEAT
REDIS_URL=YOUR_REDIS_URL_IF_USING_HEARTBEAT
HEARTBEAT=false

openssl rand -base64 36

{
  "licensee": "Example Industries Ltd",
  "valid_until": "2030-01-31",
  "signature": "<the signature from your issued license — do not edit>"
}

services:
  odxproxy:
    image: terrakernel/odxproxy:latest
    ports:
      - "6600:6600"

    volumes:
      - /home/user/odxproxy/config:/usr/share/odxproxy/config:ro
      - /home/user/odxproxy/logs:/var/log/odxproxy

    restart: unless-stopped

docker compose up -d
docker compose logs -f odxproxy

Verify the deployment

Two endpoints answer without an x-api-key, which makes them the right first check — they separate "is the proxy up and licensed" from "is my key right".

curl -s http://localhost:6600/_/license

{
  "licensee": "Example Industries Ltd",
  "valid_until": "2030-01-31",
  "is_valid": true
}

Confirm the running build:

curl -s http://localhost:6600/_/about

{
  "jsonrpc": "2.0",
  "id": "about",
  "result": { "build": "<build ULID>", "version": "0.1.0" }
}

Every response also carries an x-server: odxproxy <version> <build> header, so you can identify the build from any call:

curl -si http://localhost:6600/_/about | grep -i x-server

Prometheus metrics are at GET /_/metrics.

Collect your Odoo credentials

ODXProxy does not store Odoo credentials. They travel in each request body, which is what lets one deployment serve many Odoo instances. You need four values:

Check reachability before you involve credentials at all. /api/odoo/version asks Odoo for its public version banner, so it needs the proxy key but no Odoo credentials:

curl -s -X POST http://localhost:6600/api/odoo/version \
  -H "x-api-key: $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "01J8ZQ4M7N9K2P5R8T1V3W6X9Y", "url": "https://erp.example.com" }'

If that returns Odoo's version_info, the network path from proxy to Odoo works and your x-api-key is correct. Anything else is a connectivity or key problem, not a credentials problem.

Your first request

Everything else goes through POST /api/odoo/execute — one request shape, nine actions:

curl -s -X POST http://localhost:6600/api/odoo/execute \
  -H "x-api-key: $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "01J8ZQ4M7N9K2P5R8T1V3W6X9Y",
    "action": "search_read",
    "model_id": "res.partner",
    "params": [[["is_company", "=", true]]],
    "keyword": { "fields": ["id", "name", "email"], "limit": 10 },
    "odoo_instance": {
      "url": "https://erp.example.com",
      "db": "prod",
      "user_id": 2,
      "api_key": "<ODOO_USER_API_KEY>"
    }
  }'

The body maps onto Odoo's execute_kw almost one-to-one:

• id — a client-generated string (UUID or ULID). It is echoed back so you can correlate responses.
• action — one of the nine allowed actions. Anything else is rejected with -32001.
• model_id — the Odoo model, e.g. res.partner.
• params — a JSON array of positional args (defaults to []). For search_read the first element is the domain, hence the doubled brackets.
• keyword — a JSON object of kwargs (defaults to {}): fields, limit, offset, order, context, …
• odoo_instance — the per-request target, from the table above.

A success looks like this:

{
  "jsonrpc": "2.0",
  "id": "01J8ZQ4M7N9K2P5R8T1V3W6X9Y",
  "result": [
    { "id": 14, "name": "Acme Corp", "email": "hello@acme.example" },
    { "id": 27, "name": "Globex", "email": "contact@globex.example" }
  ]
}

Always check the response in two steps

So every client must do this, in order:

1. Is the HTTP status 200? If not, it is a proxy-level failure — surface the JSON-RPC error (see the error catalog).
2. Is error present in the body? If yes, it is an Odoo logic error — surface it. Otherwise read result.

status=$(curl -s -o body.json -w '%{http_code}' \
  -X POST http://localhost:6600/api/odoo/execute \
  -H "x-api-key: $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json)

jq --arg s "$status" \
  'if $s != "200" or .error
   then "error \(.error.code): \(.error.message)"
   else .result end' body.json

The official SDKs do both checks for you and raise typed exceptions, so you only ever handle result.

Calling anything else

Only the nine actions are directly callable. Any other Odoo method goes through call_method with a non-empty fn_name:

{
  "id": "01J8ZQ4M7N9K2P5R8T1V3W6X9Z",
  "action": "call_method",
  "model_id": "sale.order",
  "fn_name": "action_confirm",
  "params": [[42]],
  "keyword": {},
  "odoo_instance": { "url": "…", "db": "…", "user_id": 2, "api_key": "…" }
}

Omitting fn_name on a call_method returns HTTP 400 with code -32002.

Configuration reference

Every setting is read from the dotenv file at startup.

Per request, x-request-timeout (integer seconds) overrides DEFAULT_ODOO_TIMEOUT_SECS; missing, non-numeric, or 0 falls back to the default. Send Accept-Encoding: gzip, br, or deflate to get compressed responses.

Troubleshooting

The full list is in the error catalog.

Next steps

• The nine actions — what each one takes in params and keyword.
• Error codes — the full catalog and the two-step check.
• API reference — every endpoint, generated from the OpenAPI spec.
• SDKs — Python, JavaScript, Java, PHP, Swift, and .NET clients that wrap all of the above.