Skip to content
CortexDocs

Fix Cortex Defender port conflicts

For developers running local services on the same device as Cortex: the local ports Cortex requires and how to resolve a conflict.

For developers running local services on the same device as Cortex Defender.

Cortex's local ports

Defender uses local ports 9000 and 9001 for AI traffic. Desktop browser routing also uses 19090 for proxy settings; headless Linux does not use this browser-routing port. These ports must be available on the device.

A development server or another Cortex process on one of the applicable ports can prevent that listener from starting.

Fix a port conflict

Open the affected connection from Home or Connections and read the reported issue. Use Home → View health for device status. If a local port is already in use, identify its owner with your operating system's tools.

On macOS:

bash
lsof -nP -iTCP:9000 -iTCP:9001 -iTCP:19090 -sTCP:LISTEN

On Windows, use PowerShell:

plaintext
Get-NetTCPConnection -State Listen |
  Where-Object { $_.LocalPort -in 9000, 9001, 19090 } |
  Select-Object LocalAddress, LocalPort, OwningProcess

Linux headless

On a headless Linux host, inspect the two service listeners without changing their state:

bash
sudo ss -ltnp '( sport = :9000 or sport = :9001 )'
systemctl status agent-rs-mitm --no-pager
sudo journalctl -u agent-rs-mitm -n 50 --no-pager

ss identifies the listening address and owner. If a different process owns a required port, send the output to the host administrator before changing either service. A missing listener can also mean the service failed before binding; inspect the service logs.

ss output:

plaintext
State  Recv-Q Send-Q Local Address:Port Peer Address:Port Process
LISTEN 0      128    127.0.0.1:9000     0.0.0.0:*        users:(("dev-server",pid=1234,fd=8))

Here, dev-server owns port 9000. The process name and PID on your host will differ. Do not copy the example PID into a command.

Interpret the reported error

If diagnostics include failed to bind PAC HTTP server:, check which process owns port 19090. If they include another agent-rs instance holds the store lock, another Defender instance is using the same local data. Include the full diagnostic in your support request.

A store-lock conflict is not proof of a port conflict. Do not delete the lock or state database to force a second instance to run. Include the actual diagnostic and process details when escalating.

Recover with the process owner

  1. Identify the owning process and confirm whether it is expected on this device.
  2. Ask its owner to resolve the conflict through the approved service or application controls. Do not terminate an unfamiliar process.
  3. On a desktop device, return to Defender, follow the displayed recovery action, and select Check connection when offered. Confirm a successful connection check before considering the issue resolved. On headless Linux, have the host administrator apply the approved service recovery procedure and repeat the listener and service checks above.
  4. Verify a fresh capture after recovery: desktop capture and sync or headless local capture and managed upload.

Use Home → View health → Copy diagnostics when available. If copying fails or the control is disabled, retry before sharing the clipboard contents. Include the applicable port, listening address, process, and test time when contacting the Chaos Labs team.