Skip to content

Environment Variables

This document describes how to configure environment variables for working with OWOX Data Marts. The system automatically loads configuration when starting the application with the owox serve command.

OWOX Data Marts can receive environment variables in two ways:

  • From system environment - variables set directly in the runtime environment
  • From configuration file - variables loaded from a .env file

Depending on the selected database type for the backend (DB_TYPE) and identity provider (IDP_PROVIDER), you need to set the corresponding additional environment variables:

  • For DB_TYPE=mysql - add MySQL connection variables (DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD, DB_DATABASE)
  • For IDP_PROVIDER=better-auth - add Better Auth variables (IDP_BETTER_AUTH_SECRET, IDP_BETTER_AUTH_BASE_URL, etc.)
  • For Report Run execution on self-managed deployments - follow Configure a Self-Managed License Key to create a LICENSE-bound key in Project Settings → License keys, match it to PUBLIC_ORIGIN, and set it as LICENSE_KEY. Without a valid key the deployment runs as COMMUNITY: configuration stays fully available, but Report Runs finish as RESTRICTED
  • For the shared Cloud deployment - provision a separate INTERNAL-bound LICENSE_KEY through the deployment secret process; Project Settings never issues this key. It must be bound to the Cloud PUBLIC_ORIGIN, must not carry a customer billing project, and requires the complete BALANCE_ENDPOINT_* integration. Rotate it through the same secret process and retain every old signing key until the last license it signed expires
  • For the Cloud deployment that issues customer license keys - set LICENSE_ISSUANCE_ENABLED=true together with LICENSE_SIGNING_SERVICE_ACCOUNT_KEY_JSON (a user-managed key of the OWOX license service account, injected from the secret store) and the BALANCE_ENDPOINT_* variables. Self-managed deployments never set these

The complete list of all available environment variables is located in the .env.example file in the project root directory.

You can configure environment variables using one of the following methods:

By default, the owox serve command looks for a .env file in the current directory (where you run the command).

Create and edit the .env file and set the values required for your configuration:

Terminal window
# Common variables
PORT=3030
LOG_FORMAT=pretty
# Database
DB_TYPE=sqlite
SQLITE_DB_PATH=./database/backend.db
# Identity provider
IDP_PROVIDER=none

Various ways to specify the path to the file:

Terminal window
# 1. If .env is in the current directory
owox serve
# 2. If .env is in another location - via flag
owox serve --env-file /path/to/.env
owox serve -e /path/to/.env

When using containers, environment variables are passed from outside the container inside through the corresponding platform mechanisms (Docker, Kubernetes, etc.).

🐳 Containers: Environment variables are set outside the container and passed inside during startup. Inside the container, the application sees them as regular environment variables.

Most hosting platforms provide their own interface for setting environment variables. Usually it’s an “Environment Variables” or “Config Vars” section in project settings.

Some environment variables can be configured directly through command line arguments. This option provides the highest priority for configuration:

Terminal window
# Using command line arguments (highest priority)
owox serve --port 3030 --log-format json
# Combined with environment file
owox serve --env-file .env.production --port 3030

⚠️ Limited scope: Only a limited set of variables can be configured through command line arguments. Currently supported: PORT (via --port) and LOG_FORMAT (via --log-format). For other variables, use environment files or system environment variables.

Set environment variables directly before running the command:

Terminal window
# Linux/macOS/Windows (Git Bash)
DB_TYPE=sqlite SQLITE_DB_PATH=./database/backend.db IDP_PROVIDER=none owox serve
# Windows (Command Prompt)
set DB_TYPE=sqlite && set SQLITE_DB_PATH=./database/backend.db && set IDP_PROVIDER=none && owox serve
# Windows (PowerShell)
$env:DB_TYPE="sqlite"
$env:SQLITE_DB_PATH="./database/backend.db"
$env:IDP_PROVIDER="none"
owox serve

This section describes the internal logic of the environment variable loading system. Understanding this order will help you configure the correct setup and diagnose problems.

The system loads environment variables in the following priority order (highest to lowest):

1. Command Line Arguments (Highest Priority)

Section titled “1. Command Line Arguments (Highest Priority)”

Variables specified through command line arguments override all other sources:

Terminal window
owox serve --port 3030 --log-format json

⚠️ Note: Only --port and --log-format are currently supported as command line arguments.

Variables set directly in the runtime environment (system environment variables or variables set through hosting platform interfaces).

When you specify a path to a configuration file via --env-file:

Terminal window
owox serve --env-file /path/to/.env.production

If no environment file is explicitly specified, the system looks for a .env file in the current directory:

Terminal window
owox serve

If variables are not set through any of the above methods, the system uses default values:

PORT=3000
LOG_FORMAT=pretty

Example demonstrating priority:

Terminal window
# All these sources can provide PORT value:
# 1. Command line argument (highest priority): --port 3030
# 2. System environment: export PORT=3010
# 3. Explicitly specified file: PORT=3020 in custom.env
# 4. Default .env file: PORT=3000
# 5. Default value: PORT=3000 (lowest priority)
owox serve --env-file custom.env --port 3030
# Result: PORT=3030 (from command line argument)
  • PUBLIC_ORIGIN: Base public URL of the application (scheme + host [+ optional port]).

    • Examples: http://localhost:3000, https://data-marts.example.com
    • Default: http://localhost:${PORT}
    • In production, set this to your actual deployment URL.
    • For a licensed self-managed deployment, it must match the Public origin of the configured license key.
  • LOOKER_STUDIO_DESTINATION_ORIGIN: Public origin used to generate the deployment URL for the Data Studio Destination.

    • If empty, it falls back to PUBLIC_ORIGIN.
    • Example: https://looker.example.com
  • MCP_DYNAMIC_CLIENT_ALLOWED_REDIRECT_ORIGINS: Comma-separated HTTPS origins allowed as OAuth redirect targets for dynamic MCP clients.

    • Loopback HTTP redirects for desktop/CLI clients are always allowed.
    • Example for Claude web: https://claude.ai
    • Default: empty.
  • MCP_PUBLIC_BASE_URL: Public origin of the shared hosted MCP server.

    • Example: https://mcp.owox.com
    • MCP_OAUTH_RESOURCE defaults to ${MCP_PUBLIC_BASE_URL}/mcp when not set.
    • Project-specific MCP URLs are derived from this value. For MCP_PUBLIC_BASE_URL=https://mcp.owox.com, the project URL format is https://{projectId}.mcp.owox.com/mcp.
    • Do not configure a separate project-domain environment variable. The deployment must route both mcp.owox.com and *.mcp.owox.com to the same MCP backend and preserve Host, X-Forwarded-Host, and X-Forwarded-Proto.

Connect on a Sheets Source Google account Credential uses its own Google OAuth client. Without these variables the Credential form offers only the values typed by hand.

  • OAUTH_GOOGLE_SHEETS_CLIENT_ID and OAUTH_GOOGLE_SHEETS_CLIENT_SECRET: the OAuth client, of type Web application.
  • OAUTH_GOOGLE_SHEETS_REDIRECT_URI: the client’s callback URL.
  • OAUTH_GOOGLE_SHEETS_PICKER_API_KEY: an API key restricted to the Google Picker API and the web app’s referrers.
  • OAUTH_GOOGLE_SHEETS_PROJECT_NUMBER: the number of the same Cloud project, used as the Picker App ID.

Enable the Google Sheets API, the Google Picker API and the Google Drive API in that Cloud project. The Data Mart form needs the Drive API to list the spreadsheets a Credential can open; without it the form shows a spreadsheet ID or URL input. This project setting is separate from the drive.file access each user grants when they sign in. Setup steps: Google Sheets credentials.

Some advertisers sign in to Microsoft Advertising with Google. Microsoft Advertising accepts only a Google token for them: a Microsoft sign-in with the same email fails with error 126 IdentityTypeMismatch. With these variables the Microsoft Ads Credential form offers Sign in with Google next to Sign in with Microsoft. Without them it offers only Sign in with Microsoft.

  • OAUTH_MICROSOFT_ADS_GOOGLE_CLIENT_ID and OAUTH_MICROSOFT_ADS_GOOGLE_CLIENT_SECRET: a Google OAuth client of type Web application. It asks only for openid email profile, scopes that need no Google verification.
  • OAUTH_GOOGLE_REDIRECT_URI: https://<your-domain>/oauth/google/callback, registered as an authorized redirect URI of that client. Google sign-in for Storages and Destinations uses the same callback page and variable, so a deployment that offers it already has the value. Users sign in with Google on the domain this URL names.

Requests still use the Microsoft Ads developer token from OAUTH_MICROSOFT_ADS_DEVELOPER_TOKEN. Microsoft Advertising may refuse tokens of a Google client that is not your own, so use a client created in your Cloud project. Setup steps: Microsoft Ads credentials.

  • TRUST_PROXY_HOPS: Number of reverse proxies in front of the application that append to X-Forwarded-For.
    • The application’s client address (Express req.ip) is taken that many entries from the right of X-Forwarded-For; entries further left come from the client and are ignored.
    • Count the entries your proxies append. Example: 2 behind a Google Cloud external Application Load Balancer, which appends both the client address and its own.
    • A number from 0 to 10, read like the other numeric settings; a value outside that range or not a whole number stops the application at startup. A blank value means the default.
    • Default: 1.
    • 0 trusts no proxy at all: the protocol (and req.hostname) also come from the connection instead of X-Forwarded-Proto and X-Forwarded-Host. Use it only when clients connect to the application directly; behind a proxy that terminates TLS the application would see http and stop marking auth cookies Secure.
    • A value larger than the real number of proxies lets clients set their own address through X-Forwarded-For.
    • Better Auth reads X-Forwarded-For itself for its rate limits and is not affected by this setting.
  • CORS_ALLOWED_HEADERS: Additional comma-separated request headers allowed by the API CORS configuration.
    • The values are added to the default allowed headers: content-type, authorization, x-owox-authorization.
    • Example for local tunnels or proxies: CORS_ALLOWED_HEADERS=ngrok-skip-browser-warning,x-custom-header

DB_MYSQL_SSL, IDP_BETTER_AUTH_MYSQL_SSL, IDP_OWOX_MYSQL_SSL enable TLS for MySQL (mysql2). Supported formats:

  • Boolean-like (strings)

    • true → {} (enable TLS with default options: rejectUnauthorized: true)
    • false or empty → no ssl field (TLS disabled)
  • JSON object (forwarded to mysql2 TLS options)

    • Strict CA verification:
      • {"rejectUnauthorized": true}
    • Custom CA bundle (inline PEM):
      • {"rejectUnauthorized": true, "ca": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"}
    • Mutual TLS (client cert + key):
      • {"rejectUnauthorized": true, "cert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n", "key": "-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"}
    • Minimum TLS version (TLS 1.2):
      • {"minVersion": "TLSv1.2", "rejectUnauthorized": true}

See also: mysql2 official SSL documentation — https://sidorares.github.io/node-mysql2/docs/documentation/ssl

Ads connectors can resolve short links in landing URL fields to the address their service points to. Resolution runs only for known short link services (bit.ly, tinyurl.com, t.co, lnkd.in, youtu.be, amzn.to, ow.ly, buff.ly, cutt.ly, is.gd, rebrand.ly) and for the domains you list here. Links on other domains stay unchanged. In OWOX Cloud, OWOX manages this value; contact support to add a domain.

VariablePurpose
CONNECTOR_SHORT_LINK_DOMAINSComma-separated domains of your own short link services, for example links.example.com. Subdomains match too. Empty by default.

Plugins are third-party web apps embedded in a sandboxed iframe. These variables control who may publish them, how OWOX Data Marts reads their GitHub sources and how it runs their schedules.

VariablePurpose
OWOX_DEPLOYMENT_PLUGIN_PUBLISHER_API_KEY_IDSComma-separated API key IDs allowed to publish, suspend and resume plugins for the whole deployment.
GITHUB_TOKENRead-only, fine-grained PAT for reading private plugin repositories. Self-managed deployments.
GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_PRIVATE_KEYOWOX Data Marts GitHub App credentials, for reading private repositories in the cloud. Required together. The key takes the whole PEM with newlines as \n, or just its base64 body with the BEGIN/END lines stripped when a secret store mangles the armour.
GITHUB_API_BASE_URLGitHub REST base URL. Override only for GitHub Enterprise.
PLUGIN_HOST_SYNC_MIN_INTERVAL_SECOptional minimum seconds between two synchronizations of the same plugin. Defaults to 30 with GitHub App or server-token access and 300 with anonymous access. An explicit value overrides every access mode. During the cooldown, publishing reuses the last validated version.
PLUGIN_HOST_REMOTE_PROBE_TIMEOUT_MSTimeout for probing a plugin’s delivery URL. Default 8000.
PLUGIN_HOST_MAX_SCHEDULES_PER_INSTALLATIONSchedules one plugin installation may have, from 1 to 1000. Default 20. ctx.schedules.list() returns every schedule with its parameters, so this limit and the next one bound its response.
PLUGIN_HOST_MAX_SCHEDULE_PARAMETERS_KIBLargest parameters of a schedule, in KiB, from 1 to 256, the most an action’s input takes. Default 64.
PLUGIN_HOST_SCHEDULE_RETRY_SECSeconds before a schedule that could not start for a passing reason, such as an unavailable identity provider or a busy validator, tries again. From 1 to 86400. Default 60. Rounded down to the minute, never after the schedule’s next run; below 60, at the next poll.
PLUGIN_HOST_SCHEDULE_STUCK_SECSeconds after which the scheduler takes back a schedule that a replica began to start and never finished, for example because it stopped. From 600 to 86400, since a replica may spend minutes starting the schedules it claimed. Default 600.
PLUGIN_HOST_QUEUE_SWEEP_INSTALLATIONSInstallations with queued plugin runs that the sweep reads per page each minute, from 1 to 10000. Default 500.

Plugin JSON collections use a named database connection. With no additional variables it falls back option-by-option to the main DB_* configuration (and to SQLITE_DB_PATH for SQLite), which is the recommended local and self-hosted setup. A Cloud deployment can isolate this data in a separate MySQL instance by setting the variables below.

VariableFallback
PLUGIN_COLLECTIONS_DB_TYPEDB_TYPE
PLUGIN_COLLECTIONS_SQLITE_DB_PATHSQLITE_DB_PATH / default app path
PLUGIN_COLLECTIONS_DB_HOSTDB_HOST
PLUGIN_COLLECTIONS_DB_PORTDB_PORT
PLUGIN_COLLECTIONS_DB_USERNAMEDB_USERNAME
PLUGIN_COLLECTIONS_DB_PASSWORDDB_PASSWORD
PLUGIN_COLLECTIONS_DB_DATABASEDB_DATABASE
PLUGIN_COLLECTIONS_DB_MYSQL_SSLDB_MYSQL_SSL

Blank override values count as absent. The collection connection has its own migration table, and RUN_MIGRATIONS applies pending migrations to both databases. Migration status also checks both by default. A down migration targets only the main database by default; set MIGRATIONS_DATA_SOURCE=pluginCollections when intentionally reverting the latest collection migration. MIGRATIONS_DATA_SOURCE=all is rejected for down migrations because the two histories advance independently.

The publisher allowlist is the authorization model for deployment-scope publishing — it stands in for an administration panel that is deliberately not built. An unset or blank value denies everyone; it never means “any key”. A Project Admin without an allowlisted key can still publish to their own project, and any member can publish for themselves.

A vendor may name your origin in a Content-Security-Policy: frame-ancestors directive instead of allowing * or https:. The origin compared against is PUBLIC_ORIGIN, the same value the rest of the deployment uses — the page that embeds a plugin is served from it, so a plugin-specific copy could only drift away from the real one.

GitHub access falls back in order: App installation token, then GITHUB_TOKEN, then anonymous. Public repositories need no credential at all, and an App configured but not installed on a given public repository does not block it.

See the plugin authoring guide for what this means on the plugin side.

OWOX AI lets a member choose the AI of your deployment for a plugin that needs the logical ai Credential, instead of an own AI Credential. The fast and reasoning models need AI_BASE_URL, AI_API_KEY, AI_PLUGIN_FAST_MODEL and AI_PLUGIN_REASONING_MODEL, all set. AI_MODEL is never a fallback for plugins. The embedding model is available only when the chat variables and AI_PLUGIN_EMBEDDING_MODEL are set.

The decision model is on only when AI_PLUGIN_DECISION_PROVIDER, AI_PLUGIN_DECISION_BASE_URL, AI_PLUGIN_DECISION_API_KEY and AI_PLUGIN_DECISION_MODEL are all set. It does not depend on the variables of the chat models: a deployment can provide decision without fast and reasoning, and the other way round. A call to decision never falls back to a chat model. Choose a model with zero data retention where that matters; OWOX Data Marts does not check it.

VariablePurpose
AI_PROVIDERopenai or openrouter. Any other value means openai. Default openai.
AI_BASE_URLBase URL of the AI provider API.
AI_API_KEYAPI key of the AI provider.
AI_MODELModel of AI Insights. Plugins do not use it.
AI_PLUGIN_FAST_MODELModel ID that serves the fast model of plugins.
AI_PLUGIN_REASONING_MODELModel ID that serves the reasoning model of plugins.
AI_PLUGIN_EMBEDDING_MODELModel ID that serves the embedding model of plugins. Optional.
AI_PLUGIN_DECISION_PROVIDERProvider of the decision model of plugins. Only cloudflare-workers-ai. Another value stops startup.
AI_PLUGIN_DECISION_BASE_URLBase URL of the decision API. https:// only, for example https://api.cloudflare.com/client/v4/accounts/<account_id>/ai.
AI_PLUGIN_DECISION_API_KEYSecret. A Workers AI token with Workers AI - Read and Workers AI - Edit.
AI_PLUGIN_DECISION_MODELModel ID that serves the decision model of plugins, for example @cf/cloudflare/clef-flash.
AI_ALLOWED_PROVIDERSOpenRouter only. Comma-separated providers that may serve a request of AI Insights or OWOX AI. Empty by default, which sets no restriction.
AI_DATA_COLLECTIONOpenRouter only. Data collection policy sent with each request of AI Insights or OWOX AI. Default deny. An empty value means the default.
AI_ZDROpenRouter only. When true, only zero data retention providers serve a request of AI Insights or OWOX AI. Default true. An empty value means the default.

Plugin code cannot change the routing of a request. For a plugin request, a provider can ignore a call option that it does not support, for example temperature. In OWOX Cloud, each successful OWOX AI call is an AI Process Run; see Consumption units. A self-managed deployment does not bill OWOX AI calls.

These variables bound the cost of running and testing custom (no-code) connectors. All three are validated at startup: a value that is not a whole number inside the stated range stops the application with a configuration error instead of being silently ignored.

VariablePurpose
MAX_CONNECTOR_TESTS_PER_PROJECTConcurrent live connector tests (POST /connectors/custom/test) a single project may run. Default 3, range 1–1000. Mirrors MAX_CONNECTOR_RUNS_PER_PROJECT, which bounds the same class of work for scheduled runs.
MAX_CONNECTOR_TESTS_TOTALConcurrent live connector tests across all projects on one instance. Default 10, range 1–1000. See the per-instance note below.
CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MSHow often a running connector flushes its accumulated logs and errors to the database, in milliseconds. Default 2000, range 0–3600000. 0 disables incremental streaming, so logs are written once when the run ends.

MAX_CONNECTOR_TESTS_TOTAL is a per-instance limit, not a deployment-wide one — the name does not convey this. Each replica counts only the tests it is running itself and knows nothing about its peers, so a deployment of N replicas admits up to MAX_CONNECTOR_TESTS_TOTAL x N connector tests at once. Size the value against what one replica can carry, then multiply by the replica count to get the real ceiling on the backing host and on the upstream APIs being called.

Each test spawns a real Node child process that drives outbound HTTP to a host the manifest author controls, so both caps bound processes in flight rather than requests per second. The per-project cap keeps one project from taking a whole instance; the total cap keeps many projects from doing together what none of them can do alone.

A blank value for any of these three means its default, so a key templated to an empty string leaves streaming on and the caps at their defaults.

Lowering CONNECTOR_RUN_LOG_FLUSH_INTERVAL_MS increases database write volume for the entire duration of every connector run, because each flush rewrites the run’s whole log and error buffer. Raise it, or set 0, on deployments where run logs matter less than database load.

The system outputs detailed messages about the loading process to help you understand what’s happening during environment setup:

Terminal window
owox serve --env-file .env.production

Expected success messages:

  • 📂 Using specified environment file: .env.production
  • 🔄 Starting to process environment file: .env.production
  • ✅ Set 5 variables
  • ✨ Environment file processed successfully

Expected file path resolution messages:

  • 📂 Using specified environment file: /path/to/.env.production (when --env-file is specified)
  • ⚙️ Using default environment file: /current/directory/.env (default fallback)

Expected file processing messages:

  • 🔄 Starting to process environment file: .env.production
  • ✅ Set 5 variables
  • ⏭️ Skipped 2 existing variables: PORT (already exists), LOG_FORMAT (already exists)
  • 🗑️ Ignored 1 invalid variables: EMPTY_VAR (empty string value)
  • ✨ Environment file processed successfully
🔍 Environment file not found: /path/to/.env.production

Solution: Check the correctness of the file path and ensure the file exists.

📖 Failed to read file /path/to/.env: ENOENT: no such file or directory

Solution: Verify file permissions and path accessibility.

💥 Empty content or failed to parse environment file: /path/to/.env

Solution: Check the syntax of the .env file and ensure it’s not empty. The file should contain valid KEY=value pairs.

🔍 Environment file not found: /current/directory/.env
🚫 Failed to process environment file

Solution:

  1. Create a .env file in the root directory
  2. Specify the correct path via --env-file
  3. Set variables directly in the environment (without using a file):
    • Via environment variables: PORT=3030 DB_TYPE=sqlite owox serve
    • Via hosting platform environment variables interface
    • Via system environment variables

When variables are ignored or skipped, the system provides specific reasons:

  • EMPTY_VAR (empty string value) - Variable has no value after trimming
  • INVALID_KEY (invalid key) - Key is empty or contains only whitespace
  • UNDEFINED_VAR (undefined/null value) - Variable is undefined or null
  • PORT (already exists) - Variable already exists and override is disabled