Troubleshooting & FAQ

Installation

The install workspace does not show downloads

Check:

You are signed in.
Your subscription state is trialing or active.
Your package has a published installer artifact.
OmniSight can validate account state and artifact access.

Cancelled, expired, restricted, or revoked accounts cannot mint new private delivery sessions.

The server installer finishes but the browser shows a certificate warning

The server uses a local certificate for localhost, 127.0.0.1, and the detected LAN IP. On the server Mac, the installer attempts to trust the local CA. If that trust step fails, manually trust the generated CA in Keychain Access or use the local health check with curl -k only for diagnostics.

Do not use browser warning bypass as the normal agent onboarding path for other devices. Use the public Agent Installer app plus invite URL so the agent receives the CA PEM through the manifest.

Port 52443 is already in use

macOS/Linux:

bashlsof -nP -iTCP:52443 -sTCP:LISTEN

Stop the conflicting process or uninstall the previous OmniSight install before reinstalling.

The server should survive logout or reboot

Current macOS native installs use a system LaunchDaemon for the local server. If the server only runs while the installing user session exists, check for stale legacy user LaunchAgent plists and reinstall or contact support.

Account and Entitlement

Account says Trialing but downloads are blocked

Open the Account page and wait briefly after checkout return. Webhook processing can take a short time. If it remains blocked, use the local console's entitlement refresh after the server is installed.

Combined Starter cannot deploy a separate agent

Expected. Starter combined installs the server and local agent together on one computer. The Deploy Agent workspace is blocked by UI and API policy.

Use Starter Separate or a Team package for separate agent enrollment.

Seat limit reached

Starter Separate allows one separate agent. If the seat is consumed:

Uninstall the old agent from the endpoint.
Delete the old agent row from the console when appropriate.
Create a new install invite.

Install blocked: deployment or seat already reserved or active

A new server install is rejected while your package's deployment seat is reserved, claimed, or active.

Check:

The Account page deployment usage. If an existing server install is still active, uninstall it first.
If a previous install failed partway, its reservation expires automatically; retry after a short wait.
If you recently uninstalled, the deployment stays in a release quarantine (release_pending) before the seat frees. Wait for the quarantine to elapse or use Request manual release from the Account page; manual release is accepted immediately but preserves the same quarantine window.

Uninstalled the server but the seat still shows used

Expected during the release quarantine. Uninstall requests a cloud release and the deployment shows release_pending until the quarantine elapses with no further server activity. Continued heartbeat or enrollment activity after a release request flags the deployment for review instead of freeing the seat.

Agent Enrollment

Agent cannot connect to the server

Check:

server health: https://<server>:52443/health
firewall/LAN reachability
server_url in agent config
CA certificate path or PEM
agent service status

Linux:

bashsudo systemctl status omnisight-agent.service
sudo journalctl -u omnisight-agent.service -f

Invalid enrollment secret

Bootstrap tokens expire. Create a new invite or deploy token and rerun the installer. For trusted automation, verify the server-side ENROLLMENT_SECRET.

Agent is online but no events appear

Check:

collector_enabled: true
collector_emit_mode
noise filter settings
entitlement runtime state
agent logs
dashboard time range and filters

Installers currently write collector_emit_mode: delta, so only new/lifecycle changes appear after initial state is known.

DNS query events show empty type/response fields

Expected on non-Linux agents and on Linux agents where Protocol Metadata is disabled. Connection-inferred dns_query rows carry null DNS metadata fields. To collect DNS query type, response code, and answer count, enable Protocol Metadata (DNS) from the Agent Detail page for a Linux agent. The control is Linux-only and off by default.

Vulnerabilities stays on Loading or shows no software

Check:

the agent has completed at least one heartbeat
software inventory collection is enabled on the agent
the agent can POST to /api/ingest/inventory
local entitlement still allows event/inventory ingest
CVE_API_URL and CVE_API_KEY are configured on the server
the private CVE service is reachable from the self-hosted server

The Vulnerabilities page depends on endpoint software inventory first, then CVE matching. If the software table is empty, confirm inventory ingest before debugging CVE matching.

If Details -> View opens but raw CVE JSON is unavailable for a known CVE, check the same CVE integration path:

CVE_API_URL and CVE_API_KEY are configured on the server
the CVE service detail endpoint is reachable from the self-hosted server
the CVE record exists in the CVE intelligence database
the local user still has access to the Vulnerabilities page

Raw-detail failures should show a generic unavailable state in the UI. They should not expose upstream URLs, API keys, headers, or internal errors.

Alerts are empty after events arrive

Check:

the user has alerts permission
built-in detection rules are enabled on the dense triage Alerts page, or create/preview a custom detection rule from the Detection Rules panel
alert evaluation has run automatically or through Run evaluation
ALERT_EVALUATION_ENABLED=true
recent event data matches the enabled built-in/custom rule conditions, or software inventory has high/critical CVE matches

Alert evaluation intentionally creates operator alerts from metadata and inventory evidence. It does not inspect packet payloads or decrypted TLS traffic.

Config permission warning

The agent config contains credentials. It should be owner read/write only.

bashsudo chmod 600 /etc/omnisight-agent/agent.yaml

Remote Terminal

Terminal button is disabled

Possible causes:

package does not include remote terminal
REMOTE_ACCESS_ENABLED is false
agent is offline
agent remote-control websocket is disconnected
agent does not advertise terminal support
user lacks agents_remote_terminal or agents_remote_approve

Base Starter combined does not include remote terminal.

Remote terminal returns a root-user guard error

Linux services run as root by default. The agent refuses to open a root shell unless configured to switch to a non-root local user.

Set:

yamlremote_terminal_user: "local-non-root-user"

Then restart:

bashsudo systemctl restart omnisight-agent.service

remote_terminal_user: "root" is rejected.

Remote desktop/RDP is unavailable

Expected. Remote desktop is Phase 2. Current builds expose terminal routes only.

Authentication

Missing CSRF header

Cookie-authenticated mutating requests need:

textX-Requested-With: XMLHttpRequest

Browser console users should not normally see this. Clear cookies and sign in again if the UI gets stuck.

Logged out unexpectedly

Common causes:

access token expired and refresh failed
your password was changed
your user was deleted or deactivated
refresh token expired

Password changes invalidate sessions for the changed user.

Updates

Update visible in account but not local console

Check:

local entitlement status
update status endpoint
server ID registration
rollout assignment/wave eligibility
network connectivity to OmniSight managed services

OmniSight managed services are the source of truth for update visibility.

Private update check request failed

Check:

local server can reach OmniSight managed services
the signed license key in .env is still current for the subscription
the deployment has a stable ENTITLEMENT_SERVER_ID
entitlement refresh succeeds from the Account page
OmniSight has a published release for the server's update profile
the server clock is accurate enough for signed lease/update validation

Cancelled, restricted, or revoked entitlement states can intentionally block update downloads and apply actions.

One-click update apply does not show the administrator approval prompt

Current LaunchDaemon installs use the menubar helper to request administrator approval in the user's GUI session. If the prompt does not appear, confirm the menubar app is running, then retry from the Update Center. Older installs can be migrated by applying the latest native update or reinstalling from the current account workspace.

Local Data and Backups

Local data store is locked

The native local data store can have limited concurrent write behavior. For very high traffic, use a controlled operator-managed deployment profile.

Disk usage grows after many native updates

Open Storage & Retention from the sidebar and review Update backups and Managed total. Native rollback backups are retained for update safety, but old managed backups can be pruned according to the configured update-backup retention window while preserving the newest configured backups.

If cleanup reports permission-denied update backups, apply the latest native update first. The privileged update path repairs managed rollback backup ownership back to the selected runtime user, then the normal app-user cleanup can remove old eligible backups.

Backup native install

Back up:

text/usr/local/omnisight/server/.env
/usr/local/omnisight/server/endpoint_monitor.db
/usr/local/omnisight/server/cert.pem
/usr/local/omnisight/server/key.pem

Also keep the installer/account information needed to reinstall.

FAQ

How are production installers and updates delivered?

Production installer and update delivery uses managed OmniSight services, artifact storage, and short-lived delivery sessions.

What ports does OmniSight use?

Port	Purpose
52443	HTTPS console, API, ingest, and websocket routes

Can agents run without root?

Many collection paths can run without root, but Linux system packages install as a root-managed systemd service. Remote terminal sessions must target a non-root local account when the agent service runs as root.

Is connection data encrypted at rest?

Native local data is not encrypted by OmniSight by default. Use FileVault or disk-level encryption for native macOS installs. Operator-managed deployments should use the storage encryption controls of that environment.

Can I use my own TLS certificates?

Yes, but current native installer flow provisions local certificates automatically. If replacing them, keep the agent CA trust path and SERVER_PUBLIC_URL aligned.

What happens if the server is down?

Agents retry with exponential backoff and buffer events up to their configured local buffer limits. Old buffered events can be dropped when capacity is exceeded.