Server Configuration

OmniSight server configuration is stored in environment files. For the current macOS native installer, the main file is:

text/usr/local/omnisight/server/.env

The source tree also supports operator-managed deployments for controlled environments, but the public customer installer flow is macOS native.

The public marketing/account site is separate from the self-hosted server. The self-hosted server runs locally at https://localhost:52443 or the configured LAN URL. Entitlement, downloads, releases, and vulnerability lookup use managed OmniSight service endpoints configured by the installer.

Required Secrets

Variable	Description
`SECRET_KEY`	JWT/session signing secret. Must be at least 32 random characters.
`ENROLLMENT_SECRET`	Trusted fallback enrollment secret for first agent registration.

The installer generates these automatically. Do not commit or share them.

Core Application Settings

Variable	Default	Description
`APP_NAME`	`OmniSight API`	API name
`APP_VERSION`	`1.0.0` in source; installer writes package version	Version shown by `/health`
`API_PREFIX`	`/api`	API route prefix
`DEBUG`	`false`	Enables debug behavior when true; keep false in production
`PAGINATION_MAX_PAGE_SIZE`	`100`	Max API page size
`SERVER_PUBLIC_URL`	empty	Canonical URL agents and installer manifests should use, for example `https://192.168.1.83:52443`

Local Data Store

Variable	Default	Description
`DATABASE_URL`	empty -> native local store	Local data store connection string

When empty, the server uses the native local event store:

text<native-local-store>

This is the current native installer default for single-server deployments. Use an operator-managed external data store only for controlled advanced deployments that need that operational model.

Authentication and Sessions

Variable	Default	Description
`JWT_ALGORITHM`	`HS256`	Access-token signing algorithm
`ACCESS_TOKEN_EXPIRE_MINUTES`	`15`	Access token lifetime
`REFRESH_TOKEN_EXPIRE_DAYS`	`7`	Refresh token lifetime
`REQUEST_AUDIT_ENABLED`	`true`	Enables audit logging for important actions

Refresh tokens rotate on use. Password changes invalidate that user's existing sessions.

Agent and Enrollment Settings

Variable	Default	Description
`AGENT_OFFLINE_THRESHOLD_MINUTES`	`5`	Heartbeat age after which an agent is effectively offline
`AGENT_INSTALL_SESSION_TTL_MINUTES`	`30`	Lifetime of macOS invite/install sessions

New enrollment is also controlled by the signed entitlement lease. For combined Starter, separate enrollment remains blocked even when the subscription is healthy.

Remote Access

Variable	Default	Description
`REMOTE_ACCESS_ENABLED`	`false` in source	Enables remote terminal/control websocket routes
`REMOTE_ACCESS_SESSION_TTL_MINUTES`	`5`	Approval token lifetime
`REMOTE_ACCESS_IDLE_TIMEOUT_SECONDS`	`300`	Idle timeout
`REMOTE_ACCESS_HARD_TIMEOUT_SECONDS`	`3600`	Hard session timeout

Current package behavior:

Starter combined: remote terminal is not included.
Starter Separate, Team 10, Team 50: remote terminal can be enabled.
Remote desktop/RDP remains Phase 2.

The current split-server public bootstrap writes REMOTE_ACCESS_ENABLED=true for licensed split installs.

CORS

Variable	Default
`CORS_ENABLED`	`true`
`CORS_ALLOW_ORIGINS`	`http://localhost:5173,https://localhost:52443`
`CORS_ALLOW_CREDENTIALS`	`true`
`CORS_ALLOW_METHODS`	`GET,POST,PUT,DELETE,PATCH,OPTIONS`
`CORS_ALLOW_HEADERS`	`Content-Type,Authorization,X-Requested-With`

Do not use wildcard origins with cookie authentication in production.

TLS

Native macOS installs generate local certificates with:

localhost
127.0.0.1
detected LAN IP

Important trust boundary:

Browser trust on the server Mac is separate from agent runtime trust on endpoint devices.
Normal macOS agent onboarding uses the public Agent Installer app plus invite URL paste.
The invite manifest delivers the CA PEM for strict agent HTTPS transport.
Do not make normal onboarding depend on users bypassing browser TLS warnings from https://<LAN-IP>:52443.

Relevant variables:

Variable	Description
`TLS_CERT_PATH`	Optional explicit cert path used by manifest code
`SERVER_PUBLIC_URL`	Canonical server URL given to agents

Entitlement Lease

Variable	Default	Description
`ENTITLEMENT_CHECK_ENABLED`	`true`	Enable managed lease checks
`ENTITLEMENT_RUNTIME_ENFORCEMENT_ENABLED`	installer/runtime controlled; enabled in current customer packages	Enforce runtime gates on ingest paths when enabled
`ENTITLEMENT_LEASE_URL`	managed by installer	Lease endpoint
`ENTITLEMENT_LICENSE_KEY`	empty	Signed license key
`ENTITLEMENT_SERVER_ID`	empty	Stable self-hosted server ID
`ENTITLEMENT_REQUEST_TIMEOUT_SECONDS`	`5`	Lease request timeout
`ENTITLEMENT_SIGNING_PUBLIC_KEY`	empty	Public key for lease verification

Runtime capabilities include:

heartbeat_allowed
event_ingest_allowed
new_enrollment_allowed
downloads_allowed
updates_allowed
admin_read_only

Artifact Delivery

Variable	Default	Description
`ARTIFACT_DELIVERY_CATALOG_URL`	managed by installer	Private artifact catalog
`ARTIFACT_DELIVERY_SESSION_URL`	managed by installer	Short-lived download sessions
`ARTIFACT_DELIVERY_REQUEST_TIMEOUT_SECONDS`	`5`	Delivery request timeout

These endpoints gate agent and update artifacts by subscription state, package, server ID, and delivery policy.

Updates

Variable	Default	Description
`UPDATE_CHECK_ENABLED`	`true`	Enable update checks
`UPDATE_MANIFEST_URL`	managed by installer	Legacy/latest endpoint
`UPDATE_SERVER_CHECK_URL`	managed by installer	Account/server-aware update check
`UPDATE_TELEMETRY_URL`	managed by installer	Update telemetry endpoint
`UPDATE_COMPONENT`	`server`	Component
`UPDATE_CHANNEL`	`stable`	Channel
`UPDATE_RUNTIME_MODE`	`native`	Runtime mode
`UPDATE_APPLY_ENABLED`	`true`	Allow local native apply path
`UPDATE_NATIVE_INSTALL_ROOT`	`/usr/local/omnisight`	Native install root
`UPDATE_NATIVE_BACKUP_ROOT`	`~/Library/Application Support/OmniSight/updates/backups`	Backup root
`UPDATE_NATIVE_HEALTH_URL`	`https://127.0.0.1:52443/health`	Post-update health URL

Current macOS service lifecycle note:

The native server runs as a system LaunchDaemon by default.
A user-session menubar helper remains available for status display and administrator-approved update apply.
The local update relay requires a bearer token and only accepts update wrapper scripts from OmniSight's managed update directory.
Managed rollback backups are kept outside the install tree. During privileged native update apply, OmniSight repairs managed backup directory ownership back to the selected runtime user so the Storage & Retention page can prune old rollback backups later.

Storage & Retention

Storage maintenance settings are stored in the local application database and controlled from the dedicated Storage & Retention page by users with users_manage.

Default retention behavior:

events: 30 days
visible/admin audit rows: 180 days
hidden request audit rows: 30 days
log files: 14 days
update rollback backups: 7 days
newest update rollback backups retained: 2

Maintenance can prune retention-bound rows, rotate/gzip logs, checkpoint SQLite WAL, compact SQLite after a free-space preflight, and prune eligible managed update rollback backups. It reports bounded counts and byte estimates only; it does not expose file contents, log contents, database rows, environment values, certificates, or secrets.

IP Enrichment

Variable	Default
`IP_ENRICHMENT_ENABLED`	`true`
`IP_ENRICHMENT_API_URL`	`http://ip-api.com/batch`
`IP_ENRICHMENT_BATCH_SIZE`	`100`
`IP_ENRICHMENT_INTERVAL_SECONDS`	`60`
`IP_ENRICHMENT_CACHE_TTL_DAYS`	`7`
`IP_ENRICHMENT_SKIP_PRIVATE`	`true`

IP enrichment is enabled by default for every customer package. The server resolves public remote IP metadata for Events and Charts, caches results, and skips private/internal addresses by default.

CVE and Alert Evaluation

Variable	Default	Description
`CVE_API_URL`	empty	Private CVE lookup API base URL used for vulnerability matching
`CVE_API_KEY`	empty	Server-to-CVE-service API key
`ALERT_EVALUATION_ENABLED`	`true`	Enables built-in alert evaluation
`ALERT_EVALUATION_INTERVAL_SECONDS`	`300`	Background evaluation interval
`ALERT_EVALUATION_INITIAL_DELAY_SECONDS`	`10`	Delay after startup before first evaluation
`ALERT_EVENT_WINDOW_HOURS`	`24`	Event lookback window for event-based detections
`ALERT_VULNERABILITY_SCAN_LIMIT`	`25`	Software inventory rows evaluated per vulnerability scan batch

Alert evaluation creates SIEM alerts from endpoint telemetry and vulnerability findings. Built-in rules cover cleartext endpoint HTTP metadata and high/critical CVE matches. Admin and network-admin users can also create custom detection rules across supported event telemetry, preview rules before saving, start from reusable templates, and use automatic MITRE ATT&CK mapping. The current Alerts UI uses a dense triage layout with status, verdict, owner assignment, unassignment, notes, suppression management, maintenance windows, and audit-backed changes.

The same CVE API configuration is used for batch vulnerability matching and single-CVE raw detail lookup from the Vulnerabilities page. The browser receives only the self-hosted server response; the CVE API key, upstream URL, headers, and internal upstream errors are not exposed.

Ingest Rate Limiting

Variable	Default	Description
`INGEST_TRUSTED_PROXY_CIDRS`	empty	Trusted reverse proxy CIDRs
`INGEST_TRUST_PROXY_HEADERS`	`false`	Trust proxy headers only when the proxy is controlled

Default rate limits:

Scope	Endpoint	Limit
Source IP	Heartbeat	12,000/min
Source IP	Events	24,000/min
Agent	Heartbeat	120/min
Agent	Events	600/min

Native `.env` Example

envAPP_NAME=OmniSight API
APP_VERSION=<installed-package-version>
API_PREFIX=/api
DEBUG=false

SECRET_KEY=<generated>
ENROLLMENT_SECRET=<generated>
DATABASE_URL=
STATIC_DIR=../dist

SERVER_PUBLIC_URL=https://192.168.1.83:52443
REMOTE_ACCESS_ENABLED=true
IP_ENRICHMENT_ENABLED=true
CVE_API_URL=<private-cve-api-url>
CVE_API_KEY=<issued-cve-api-key>
ALERT_EVALUATION_ENABLED=true

ENTITLEMENT_CHECK_ENABLED=true
ENTITLEMENT_LICENSE_KEY=<issued-license-key>
ENTITLEMENT_SERVER_ID=<stable-server-id>
ENTITLEMENT_LEASE_URL=<managed-lease-endpoint>
ENTITLEMENT_SIGNING_PUBLIC_KEY=<control-plane-public-key>

UPDATE_CHECK_ENABLED=true
UPDATE_RUNTIME_MODE=native
UPDATE_CHANNEL=stable
MENUBAR_RELAY_TOKEN=<generated>