OpenOpps docs / Reference
Configuration
Runtime settings, environment variables, and concurrency controls.
OpenOpps loads settings from OPENOPPS_ environment variables and an optional local .env file. Unknown .env keys are ignored. Treat configuration as local runtime wiring: the CLI writes to the SQLite URL you point it at and reads plugins from the Python environment that launched the command.
Invocation Scope
Both invocation styles use the same settings model:
uv run openopps status
uv tool install -e .
openopps statusThe editable uv tool install -e . path makes the openopps command available directly from the current checkout. Relative SQLite URLs such as sqlite:///openoppsdb.sqlite are resolved by the running process, so keep your working directory and OPENOPPS_DB_URL explicit when switching between projects or smoke-test databases.
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
OPENOPPS_DB_URL | sqlite:///openoppsdb.sqlite | Database URL used by storage commands and sync jobs. |
OPENOPPS_MAX_CONNECTIONS | 40 | Maximum HTTP connection pool size. |
OPENOPPS_SOURCE_CONCURRENCY | 4 | Source adapter concurrency for aggregate board discovery. |
OPENOPPS_SOURCE_TIMEOUT_SECONDS | 900.0 | Maximum seconds one source adapter can run before timed-out skip. |
OPENOPPS_SOURCE_FRESHNESS_SECONDS | 0.0 | Skip recently synced source catalogs during unscoped full-sync retries. |
OPENOPPS_BOARD_CONCURRENCY | 16 | Board-level concurrency during sync workflows. |
OPENOPPS_PROVIDER_CONCURRENCY | 12 | Provider job-fetch concurrency across job-capable routes. |
OPENOPPS_WORKDAY_CONCURRENCY | 2 | Conservative limit for public Workday CXS careers-site requests. |
OPENOPPS_DB_BATCH_SIZE | 500 | Batch size for SQLite writes. |
OPENOPPS_HTTP_TIMEOUT | 30.0 | HTTP timeout in seconds. |
OPENOPPS_RETRY_ATTEMPTS | 3 | Number of retry attempts for retriable upstream requests. |
OPENOPPS_USER_AGENT | openopps/0.1 openopps@wyattowalsh.com | User agent sent to public source and provider endpoints. |
OPENOPPS_CACHE_ENABLED | true | Enables the shared JSON request cache in the SQLite database. |
OPENOPPS_CACHE_TTL_SECONDS | 3600 | Default cache freshness window in seconds. |
OPENOPPS_CACHE_REFRESH | false | Bypasses cache reads while still updating successful responses. |
OPENOPPS_CACHE_STALE_ON_ERROR | false | Allows eligible stale cache data after retryable upstream errors. |
OPENOPPS_PLUGIN_AUTOLOAD | false | Execute every discovered plugin entry point without allow-listing. |
OPENOPPS_PLUGIN_DISABLED | empty | Comma-separated plugin entry-point names to skip. |
OPENOPPS_PLUGIN_ALLOWED | empty | Comma-separated plugin entry-point names allowed to execute. |
OPENOPPS_NO_INTRO | unset | Suppress the interactive startup portal animation. |
Examples
OPENOPPS_DB_URL=sqlite:///data/openopps.db uv run openopps admin db status
OPENOPPS_PROVIDER_CONCURRENCY=4 uv run openopps jobs sync --provider workday --profile
OPENOPPS_USER_AGENT='openopps/0.1 (contact: jobs@example.com)' uv run openopps admin sources test ycFor repeated local use from the repository checkout, place values in .env at the repository root:
OPENOPPS_DB_URL=sqlite:///openoppsdb.sqlite
OPENOPPS_SOURCE_CONCURRENCY=4
OPENOPPS_SOURCE_TIMEOUT_SECONDS=900
OPENOPPS_SOURCE_FRESHNESS_SECONDS=0
OPENOPPS_PROVIDER_CONCURRENCY=12
OPENOPPS_CACHE_TTL_SECONDS=3600
OPENOPPS_PLUGIN_ALLOWED=trusted-plugin
OPENOPPS_PLUGIN_DISABLED=broken-pluginUnscoped jobs sync targets all persisted ready routes. Use explicit CLI filters such as --source, --board, or --provider for one-off scoped syncs.
The docs Jobs and Explorer surfaces read a committed static search snapshot generated from your local kaggle/openoppsdb.sqlite export. Refresh it with just docs-search-index after updating the database; see Operations for validation commands.
Docs-app telemetry is configured separately from CLI runtime settings. When instrumentation is enabled, keep collection env-gated: default to a no-op sink in local development, use local-event-lake for canonical raw events on persistent disk, and set OPENOPPS_POSTHOG_PROJECT_API_KEY only when a sanitized hosted product-analytics mirror is desired. Browser PostHog replay is a separate opt-in through NEXT_PUBLIC_OPENOPPS_POSTHOG_PROJECT_API_KEY; it remains gated by NEXT_PUBLIC_OPENOPPS_TELEMETRY_ENABLED=true, disables automatic PostHog pageview/autocapture events, masks text and inputs, disables network body/header capture, and leaves replay sampling plus trigger controls to the PostHog project. See Data Model for the event shape and Operations for operating guidance.
Flags vs Persistent Settings
Prefer flags for one run and environment variables for durable local policy:
| Need | Prefer |
|---|---|
| Refresh one upstream read | --refresh-cache |
| Always bypass cache reads in a shell/session | OPENOPPS_CACHE_REFRESH=true |
| Narrow one job sync | --source, --board, or --provider |
| Lower Workday pressure across all runs | OPENOPPS_WORKDAY_CONCURRENCY=1 or 2 |
| Hide the animation once | --no-intro |
| Hide the animation everywhere | OPENOPPS_NO_INTRO=1 |
By default, discovered plugins are visible but not executed. Set OPENOPPS_PLUGIN_ALLOWED to run specific trusted entry points. If OPENOPPS_PLUGIN_AUTOLOAD=true, every discovered plugin is eligible unless its entry-point name appears in OPENOPPS_PLUGIN_DISABLED. Disabled entries are still skipped even if also allow-listed.
For CLI one-offs, prefer command flags such as --source and --refresh-cache over persistent environment changes.
Do not commit .env files with private or environment-specific values.