docs: add ODOO_DATABASE docs and installer support for multi-database Odoo

- README: document ODOO_DATABASE flag and multi-database workflow
- docs/installation.md: document optional database prompt
- install.sh: add Odoo database prompt
- install.ps1: add ConvertToDotenvValue, Write-DotenvFile, and database prompt
- .env.example: add ODOO_DATABASE with documentation comment

Author: nicolasramos

.env.example

@@ -1,5 +1,7 @@
 # Odoo Agent Runtime Configuration
 ODOO_URL=http://localhost:8069
+# Optional multi-database Odoo: set database name; blank preserves single-database behavior (runtime follows /web/login?db=<URL-encoded database> and retains its session cookie before API calls; never put API keys in URLs).
+ODOO_DATABASE=
 API_KEY=your-runtime-api-key-here
 RUNTIME_NAME=my-machine
 POLL_INTERVAL=10

README.md

@@ -19,7 +19,7 @@ It supports Linux, macOS, and Windows.
 
 1. Create a runtime in Odoo and generate its API key.
 2. Install this runtime on the machine that will execute agent CLIs.
-3. Enter Odoo URL, API key, runtime name, and poll interval.
+3. Enter Odoo URL, optional database name, API key, runtime name, and poll interval.
 4. Choose manual mode or background service mode.
 5. Confirm the runtime appears online in Odoo.
 6. Assign agents to this runtime and send Project tasks to them.
@@ -40,6 +40,7 @@ curl -fsSL https://raw.githubusercontent.com/nicolasramos-es/odoo-agent-runtime/
 The installer asks for:
 
 - Odoo URL;
+- optional Odoo database name for multi-database instances;
 - runtime API key;
 - runtime display name;
 - polling interval;
@@ -71,6 +72,7 @@ The runtime reads `.env` and accepts CLI flags.
 | Variable | Flag | Required | Default | Description |
 | --- | --- | --- | --- | --- |
 | `ODOO_URL` | `--odoo-url` | No | `http://localhost:8069` | Odoo base URL. |
+| `ODOO_DATABASE` | `--odoo-database` | No | empty | Database name for a multi-database Odoo instance. When set, the runtime follows `/web/login?db=<URL-encoded database>` before runtime API calls and retains the selected database's session cookie. Omit or leave blank to preserve single-database behavior. |
 | `API_KEY` | `--api-key` | Yes | empty | Runtime API key generated in Odoo. |
 | `RUNTIME_NAME` | `--name` | No | host name | Display name shown in Odoo. |
 | `POLL_INTERVAL` | `--poll-interval` | No | `10` | Seconds between polling cycles. |
@@ -80,11 +82,14 @@ Example:
 ```bash
 python3 daemon.py \
   --odoo-url https://odoo.example.com \
+  --odoo-database "customer-production" \
   --api-key "YOUR_RUNTIME_KEY" \
   --name "agent-worker-01" \
   --poll-interval 5
 ```
 
+`ODOO_DATABASE` is optional. Use it only when the Odoo server hosts multiple databases. The database selection request follows redirects and keeps the resulting session cookie for subsequent runtime API calls. Do not put API keys in URLs; configure `API_KEY` through `.env` or `--api-key`.
+
 ## Command placeholders
 
 Odoo sends each agent's `cli_command`. The runtime replaces these placeholders:
@@ -129,6 +134,7 @@ See [`docs/engine-examples.md`](docs/engine-examples.md) for Codex, Hermes, Open
 | --- | --- |
 | `API key is required` | Set `API_KEY` in `.env` or pass `--api-key`. |
 | Runtime does not appear online | Check `ODOO_URL`, API key, firewall, and Odoo logs. |
+| Runtime stops before API calls on a multi-database server | Verify `ODOO_DATABASE` matches the database name and that `ODOO_URL` can reach its login page. Leave `ODOO_DATABASE` blank for a single-database server. |
 | Execution remains queued | Confirm the agent is assigned to this runtime and the daemon is running. |
 | Execution fails with CLI not found | Install the CLI on this host or fix the agent `cli_command` in Odoo. |
 | Service does not start | Run the daemon manually first, then inspect system logs. |

docs/installation.md

@@ -57,6 +57,12 @@ Scheduled Task mode is available from the installer when selected.
 | Runtime name | `agent-worker-01` |
 | Poll interval | `10` |
 
+### Optional Odoo database
+
+`ODOO_DATABASE` is optional for a single-database Odoo deployment. Provide it when the Odoo URL serves multiple databases, or when your runtime must always target one specific database. On Linux and macOS, enter it at the `install.sh` prompt; on Windows, enter it at the `install.ps1` prompt. Each installer writes an empty value when it is not needed.
+
+Keep the runtime API key separate from the Odoo URL. Enter it only at the **Runtime API key** prompt; never append it to a URL, query string, bookmark, or command history.
+
 ## Existing `.env`
 
 The installer does not silently overwrite `.env`. If `.env` exists, it asks before replacing it. If you decline, it writes `.env.new` and does not install/start a background service with stale settings.

install.ps1

@@ -16,6 +16,24 @@ function AskYesNo($Prompt, $Default = "no") {
     if (-not $value) { $value = $Default }
     return $value.ToLower() -in @("y", "yes")
 }
+function ConvertToDotenvValue($Value) {
+    if ($Value -match "[\r\n]") {
+        throw "Configuration values cannot contain line breaks."
+    }
+    # python-dotenv decodes backslash and double-quote escapes in double quotes.
+    # Dollar signs and backticks are already literal, so escaping them corrupts values.
+    return $Value.Replace('\', '\\').Replace('"', '\"')
+}
+function Write-DotenvFile($Path) {
+    @(
+        "# Odoo Agent Runtime Configuration"
+        ('ODOO_URL="{0}"' -f (ConvertToDotenvValue $OdooUrl))
+        ('ODOO_DATABASE="{0}"' -f (ConvertToDotenvValue $OdooDatabase))
+        ('API_KEY="{0}"' -f (ConvertToDotenvValue $ApiKey))
+        ('RUNTIME_NAME="{0}"' -f (ConvertToDotenvValue $RuntimeName))
+        ('POLL_INTERVAL="{0}"' -f (ConvertToDotenvValue $PollInterval))
+    ) | Out-File -FilePath $Path -Encoding ASCII
+}
 
 Write-Host ""
 Write-Host "Odoo Agent Runtime Installer (Windows)"
@@ -38,6 +56,7 @@ if (-not $python) {
 Log "Python found"
 
 $OdooUrl = Ask "Odoo URL" "http://localhost:8069"
+$OdooDatabase = Ask "Odoo database (optional; required for multi-database Odoo)"
 $ApiKey = Ask "Runtime API key"
 while ([string]::IsNullOrWhiteSpace($ApiKey)) {
     Err "Runtime API key cannot be empty."
@@ -69,13 +88,7 @@ if ((Test-Path $envFile) -and -not (AskYesNo "Existing .env found. Overwrite it?
     Warn "Keeping existing .env. Writing new configuration to .env.new."
 }
 
-@"
-# Odoo Agent Runtime Configuration
-ODOO_URL=$OdooUrl
-API_KEY=$ApiKey
-RUNTIME_NAME=$RuntimeName
-POLL_INTERVAL=$PollInterval
-"@ | Out-File -FilePath $envFile -Encoding ASCII
+Write-DotenvFile $envFile
 Log "$(Split-Path -Leaf $envFile) written"
 if ((Split-Path -Leaf $envFile) -ne ".env") {
     Warn "Scheduled Task creation skipped because the active .env was not overwritten."

install.sh

@@ -29,6 +29,26 @@ ask_yes_no() {
         *) return 1 ;;
     esac
 }
+dotenv_value() {
+    local value="$1"
+    if [[ "$value" == *$'\n'* || "$value" == *$'\r'* ]]; then
+        error "Configuration values cannot contain line breaks."
+        exit 1
+    fi
+    # python-dotenv decodes backslash and double-quote escapes in double quotes.
+    # Dollar signs and backticks are already literal, so escaping them corrupts values.
+    printf '%s' "$value" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g'
+}
+write_env_file() {
+    {
+        printf '%s\n' '# Odoo Agent Runtime Configuration'
+        printf 'ODOO_URL="%s"\n' "$(dotenv_value "$ODOO_URL")"
+        printf 'ODOO_DATABASE="%s"\n' "$(dotenv_value "$ODOO_DATABASE")"
+        printf 'API_KEY="%s"\n' "$(dotenv_value "$API_KEY")"
+        printf 'RUNTIME_NAME="%s"\n' "$(dotenv_value "$RUNTIME_NAME")"
+        printf 'POLL_INTERVAL="%s"\n' "$(dotenv_value "$POLL_INTERVAL")"
+    } > "$ENV_FILE"
+}
 
 OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -58,6 +78,7 @@ log "Python found: $($PYTHON --version)"
 printf '\n'
 info "Configuration"
 ODOO_URL="$(ask 'Odoo URL' 'http://localhost:8069')"
+ODOO_DATABASE="$(ask 'Odoo database (optional; required for multi-database Odoo)')"
 API_KEY="$(ask 'Runtime API key')"
 while [ -z "$API_KEY" ]; do
     error "Runtime API key cannot be empty."
@@ -98,13 +119,7 @@ if [ -f "$ENV_FILE" ] && ! ask_yes_no "Existing .env found. Overwrite it?" "no";
     warn "Keeping existing .env. Writing new configuration to .env.new."
 fi
 
-cat > "$ENV_FILE" <<EOF
-# Odoo Agent Runtime Configuration
-ODOO_URL=$ODOO_URL
-API_KEY=$API_KEY
-RUNTIME_NAME=$RUNTIME_NAME
-POLL_INTERVAL=$POLL_INTERVAL
-EOF
+write_env_file
 log "$(basename "$ENV_FILE") written"
 if [ "$(basename "$ENV_FILE")" != ".env" ]; then
     warn "Background service install skipped because the active .env was not overwritten."