Troubleshooting

The app runs a background agent and talks to it on localhost:2300. Nearly every "the app will not start" report comes down to one thing: another program is holding that port.

What you see	What it usually means
Something Went Wrong, and Restart changes nothing	Something else holds port 2300
Stuck on Connecting to backend	Same
A trace opens but the signal list stays empty	The app is talking to a different machine's agent
Signals appear that did not come from this machine	Same

Quick fix

This clears the most common cause in under a minute.

1. Quit Zelos completely.

2. Remove any agent left behind by a previous session:

   WindowsmacOSUbuntu

   Get-Process zelos-app-agent -ErrorAction SilentlyContinue | Stop-Process -Force
   

   pkill -f zelos-app-agent
   

   pkill -f zelos-app-agent
   

3. Launch Zelos again.

Still broken? Work through the steps below.

Find what is holding port 2300

Quit Zelos first, so the only thing left is whatever is in the way.

WindowsmacOSUbuntu

Get-NetTCPConnection -LocalPort 2300 -State Listen -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, OwningProcess,
    @{n='Name';e={(Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName}}

lsof -nP +c 0 -iTCP:2300 -sTCP:LISTEN

sudo ss -ltnp 'sport = :2300'

No output means the port is free, and the problem is something else. Skip to When the port is free.

Otherwise, find the process name in this table:

Process	Cause	Go to
Cursor, cursor, Code, code, ssh	Your editor forwarded a remote port	Editor port forwarding
zelos-app-agent	An agent from a previous session is still running	A leftover agent
zelos-agent	The headless agent is installed on this machine	The headless agent
docker, com.docker.backend	A container publishes port 2300	Stop the container, or publish it on another port
wslrelay, System, or PID 4	Something inside WSL holds the port	Something inside WSL
Anything else	—	Release the port by force

Editor port forwarding

VS Code and Cursor automatically forward ports they find on a machine you open over Remote-SSH. If that machine runs a Zelos agent on 2300, your editor clones it onto your own port 2300 and the app loses its backend.

This produces both symptoms, depending on whether the SSH connection is healthy:

• The connection is live. The app starts and looks normal, but every request goes to the remote machine's agent. Open a local .trz and the signal list is empty, because that file does not exist on the machine actually answering.
• The connection has dropped. The forwarded port still accepts connections but answers nothing, so the app never finishes starting.

Stop the forward now: open the PORTS panel, right-click port 2300, and choose Stop Forwarding Port. Closing the remote window does the same thing.

Stop it from coming back by adding this to your User settings, on the machine running the editor:

"remote.portsAttributes": {
  "2300": { "onAutoForward": "ignore" }
}

ignore means the port is never forwarded. To disable auto-forwarding for every port, set "remote.autoForwardPorts": false instead.

You do not need a tunnel to see a remote machine's data

Connect to it directly instead. Open the right sidebar, go to Data Sources, click New agent, and enter <hostname>:2300. Details in Connect to Data.

A leftover agent

The agent normally shuts down with the app. It can outlive it when the app is force-quit, crashes, or the machine sleeps mid-session. The old agent keeps the port, so every relaunch hits the same error.

WindowsmacOSUbuntu

Get-Process zelos-app-agent -ErrorAction SilentlyContinue | Stop-Process -Force

pkill -f zelos-app-agent

pkill -f zelos-app-agent

Restarting the computer has the same effect, and takes longer.

The headless agent

If you installed the standalone agent on this machine, it takes port 2300 first and the app's own agent never starts. The app may open anyway, but it is driving the headless agent rather than its own, and app features will behave oddly. Run one or the other on a single machine.

The standalone agent ships as a systemd service on Ubuntu and Debian:

sudo systemctl stop zelos-agent
sudo systemctl disable zelos-agent   # keep it stopped across reboots

Something inside WSL

Windows reports a port held inside WSL as wslrelay, System, or PID 4. Killing those from Windows does not work, and PID 4 cannot be stopped at all.

Open your WSL shell and deal with it there:

sudo ss -ltnp 'sport = :2300'   # find it
sudo fuser -k 2300/tcp     # stop it

A Zelos agent running inside WSL is the usual answer. Stop it, or move the app and the agent onto the same side.

Release the port by force

When you cannot identify the program, or it will not close cleanly, terminate whatever holds the port.

WindowsmacOSUbuntu

Get-NetTCPConnection -LocalPort 2300 -State Listen -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty OwningProcess -Unique |
  ForEach-Object { Stop-Process -Id $_ -Force }

kill -9 $(lsof -t -nP +c 0 -iTCP:2300 -sTCP:LISTEN)

sudo fuser -k 2300/tcp

This closes the owning program

If your editor holds the port, it closes with everything unsaved in it. Try closing the program normally first. On Windows, run the terminal as Administrator if you get Access Denied.

Confirm the fix

Launch Zelos, then run the find command again. You want exactly one row: address 127.0.0.1, process zelos-app-agent. That is the app's own agent, so the app is talking to this machine.

When the port is free

Windows: missing Visual C++ runtime

The agent needs the Microsoft Visual C++ runtime, and fails to launch without it.

1. Download the VC++ Redistributable x64.
2. Run the installer, then restart your computer.
3. Launch Zelos again.

Still stuck

Click Report a problem on the error screen. It sends us your description along with recent logs and system information, so we can see what happened without another round of questions.

If Zelos is running, the same thing lives under Settings → Data → Diagnostics → Report a problem.

You can also email [email protected].