Configuration reference
Configuration exists at three levels: deployment configuration controls licensed runtime behavior; Tenant/Workspace configuration controls customer-owned resources; project/run configuration controls a particular measurement program. Keep these boundaries separate.
Configuration topology
Deployment environment variables
Product and internal runtime
| Variable | Required | Purpose |
|---|---|---|
THYRIS_LICENSE_GEO_SERVICES | Deployment-dependent | Explicit GEO product license override |
GEO_INTERNAL_WORKER_TOKEN | Production | Shared internal bearer credential for BFF, workers and GEO runtimes |
GEO_CONTROL_PLANE_URL | Worker runtimes | Internal control-plane base URL |
GEO_SERVICE_KEY | Each domain runtime | Selects the single advertised domain capability |
GEO_SERVICE_ADDR | No | Listen address; default :8080 |
GEO_WORKER_INTERVAL | No | Worker poll interval; minimum 1s, default 15s |
Use a long random internal token from a secret. Do not use the token as a customer API key and do not expose internal worker routes publicly.
Domain service URLs
| Variable | Default service |
|---|---|
GEO_CORE_SERVICE_URL | http://geo-core-service:8080 |
GEO_COMPONENT_SERVICE_URL | http://geo-component-service:8080 |
GEO_OBSERVATION_SERVICE_URL | http://geo-observation-service:8080 |
GEO_INTELLIGENCE_SERVICE_URL | http://geo-intelligence-service:8080 |
GEO_KNOWLEDGE_SERVICE_URL | http://geo-brand-knowledge-service:8080 |
GEO_CONTENT_SERVICE_URL | http://geo-content-service:8080 |
GEO_CHANNEL_SERVICE_URL | http://geo-channel-service:8080 |
GEO_SIMULATION_SERVICE_URL | http://geo-simulation-service:8080 |
GEO_ACTION_SERVICE_URL | http://geo-action-service:8080 |
GEO_REPORTING_SERVICE_URL | http://geo-reporting-service:8080 |
GEO_TRACKING_SERVICE_URL | http://geo-tracking-service:8080 |
GEO_ATTRIBUTION_SERVICE_URL | http://geo-attribution-service:8080 |
GEO_ENTITY_SERVICE_URL | http://geo-entity-service:8080 |
GEO_CITATION_GRAPH_SERVICE_URL | http://geo-citation-graph-service:8080 |
GEO_PROMPT_DEMAND_SERVICE_URL | http://geo-prompt-demand-service:8080 |
GEO_NARRATIVE_SERVICE_URL | http://geo-narrative-service:8080 |
GEO_EXPERIMENT_SERVICE_URL | http://geo-experiment-service:8080 |
GEO_AUTOPILOT_SERVICE_URL | http://geo-autopilot-service:8080 |
Service URLs must resolve through internal service discovery. The control plane validates capability responses before relying on a runtime.
Connector safety overrides
| Variable | Default | Guidance |
|---|---|---|
GEO_CONNECTOR_ALLOW_INSECURE_HTTP | false | Development only; production endpoints should use HTTPS |
GEO_CONNECTOR_ALLOW_PRIVATE_NETWORK | false | Enable only for reviewed private integration networks |
Endpoints containing URL credentials are rejected. Loopback, private, link-local and internal host destinations remain blocked unless the explicit policy allows them; resolved addresses are also checked to reduce DNS-based SSRF bypass.
Provider configuration
| Field | Validation and behavior |
|---|---|
| Profile | Active platform profile or custom |
| Name | Workspace display name, 2–255 characters |
| Type | openai_compatible, anthropic_compatible, perplexity_compatible, or custom_agent |
| Endpoint URL | Valid safe URL; profile default may apply |
| Model | Required model identifier, maximum 255 characters |
| API key | Encrypted when stored; never returned after save |
| Credential secret reference | Optional server-side reference such as env://GEO_PROVIDER_API_KEY |
| Default | One default active provider per workspace |
| Capabilities | Vision, JSON mode and tool support flags |
| Web search | Available only for eligible direct OpenAI, Anthropic, Perplexity, and Gemini profiles; may add provider charges |
| Input price per million | Non-negative workspace-provider rate used for estimates |
| Output price per million | Non-negative workspace-provider rate used for estimates |
| Web-search price per request | Non-negative rate applied to provider-reported search requests |
| Pricing currency | Three-letter currency stored with each usage event |
| Configuration | Provider-specific JSON object |
| Status | Draft, active, degraded or disabled |
Use either an encrypted API key or secret reference according to deployment policy. When deleting the default provider, the oldest remaining active provider becomes default; confirm that fallback is acceptable before deletion. Provider rates come from the workspace owner's contract and are not credentials. Zero rates without a provider-reported total produce unpriced usage rather than a confirmed free-cost claim.
Observation connector configuration
Observation connectors can represent fixture, openai_compatible, anthropic_compatible, perplexity_compatible, custom_agent, mcp, rag, or workflow execution.
| Field | Purpose |
|---|---|
| Component | Optional link to a workspace-owned AI component |
| Endpoint URL | Required for executable connectors except fixture/MCP/RAG cases where configuration supplies the execution contract |
| Secret reference | Server-side credential reference |
| Terms URL/acceptance | Provider terms and retention acknowledgement |
| Retention days | Connector evidence policy, 1–365 days |
| Store raw response | Explicit raw-response retention choice |
| Configuration JSON | Adapter-specific request/version/options |
| Status | Draft, active, degraded or disabled |
Executable non-fixture connectors cannot become active without required terms acceptance. Raw-response storage should remain off unless there is a documented purpose and access/retention policy.
Monitoring schedule configuration
| Label | Cron | Execution |
|---|---|---|
| Hourly | 0 * * * * | Start of the next UTC hour |
| Daily | 0 9 * * * | 09:00 UTC daily |
| Weekly | 0 9 * * 1 | Monday 09:00 UTC |
| Monthly | 0 9 1 * * | Day 1 at 09:00 UTC |
A schedule also declares project, prompt sets, provider IDs, optional target IDs, repetitions, maximum requests, maximum cost, timezone metadata, status and next-run state. Only the supported schedules above are accepted by the current scheduler contract.
Tracking-site configuration
| Field | Contract |
|---|---|
| Hostname | Canonical site host |
| Allowed origins | One or more allowed HTTPS origins/hosts |
| Consent mode | required, granted, denied, or not_required |
| Retention days | 1–730 days |
| Site token | One-time shown, hashed at rest, revocable and optionally expiring |
| Status | Active/inactive operational state |
Sessions use a retention cap appropriate to pseudonymous continuity, while events follow site/workspace retention policy. Test the actual cleanup worker before production collection.
API key configuration
Choose account, workspace or custom-workspace scope and only the permissions required:
| Permission | Capability |
|---|---|
geo:read | Read authorized datasets, reports, graph and MCP read tools |
geo:signals:write | Send approved signal/event data where supported |
geo:draft | Create draft resources without approval/execution authority |
geo:approve | Record governed approvals where policy permits |
geo:execute | Execute approved actions where policy and route permit |
geo:write | Current mutation and MCP approval-request operations |
Set an expiration, rotate keys, and revoke before deletion. A key scope never overrides workspace membership or product access.
Environment checklist
| Configuration | Development | Staging | Production |
|---|---|---|---|
| Database and object storage | Isolated local | Isolated staging | HA/backup and restore-tested |
| Provider credentials | Test/low-limit | Sandbox/staging | Production, least privilege |
| Channel destinations | Fixture/local where safe | Staging workspace/site | Approved production destination |
| Tracking tokens | Development origin | Staging origin | Production origins only |
| Connector HTTP/private override | May be explicitly enabled | Prefer disabled | Disabled unless formally reviewed |
| Worker budgets/concurrency | Small | Production-like bounded | Monitored and alerting |
| Retention | Short test policy | Acceptance policy | Approved privacy policy |
Configuration acceptance
After a configuration change:
- Verify workspace/account ownership and actor permission.
- Validate endpoint, JSON and secret reference without logging the secret.
- Run health/capability or preview test.
- Confirm audit event and redaction.
- Execute a bounded representative operation.
- Inspect failure behavior and rollback/revocation path.
- Record owner and review date.