Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/kitephp/CLIProxyAPI-Tray/llms.txt

Use this file to discover all available pages before exploring further.

CLIProxyAPI Tray manages the cli-proxy-api.exe process. This page explains what happens behind the scenes when you start, stop, or restart the service.

​
Starting the service

When you click Start in the tray menu, the tray performs the following sequence:
1

Check for a configured password

The tray reads config.yaml and looks for a non-empty remote-management.secret-key. If the key is missing or empty, a prompt asks you to enter a password before continuing. If you cancel, the start is aborted with a “Password not set. Start cancelled.” balloon tip.
2

Check for an installed version

The tray verifies that a CLIProxyAPI binary exists in the versions/ directory. If no version is installed, a dialog appears with the latest available version and asks permission to download it. If you decline and no existing version is found, the start is aborted.
3

Stop any running instance

Before launching a fresh process, the tray kills any currently running cli-proxy-api process and waits 200 ms to ensure it has fully stopped.
4

Launch the process

The tray starts cli-proxy-api.exe with the argument --config "path/to/config.yaml" in a hidden window (no console window appears).
Start-Process -FilePath $exePath -ArgumentList '--config "config.yaml"' -WindowStyle Hidden
5

Wait for the port to become ready

The tray polls the configured port with a TCP connection check, waiting up to 12 seconds for the port to start accepting connections.
6

Report the result

  • Port ready: Shows a “Started CLIProxyAPI” balloon tip. If Auto Open WebUI is enabled, waits 1 second then opens the WebUI in the default browser.
  • Port not ready within 12 seconds: Shows a “Started, but port not ready yet” warning balloon tip. The process may still be starting — check the WebUI manually after a moment.
The port is read from config.yaml each time the service starts. The default port is 8317. Change the port: value in config.yaml to use a different port.

​
Stopping the service

Clicking Stop in the tray menu:
  1. Calls Stop-Process -Force on any process named cli-proxy-api.
  2. Waits 200 ms for the process to fully terminate.
  3. Updates the tray icon and menu state.
  4. Shows a “Stopped” balloon tip.
Stop does not wait for in-flight requests to complete. It sends a forced kill signal immediately.

​
Restarting the service

Restart runs the exact same sequence as Start — it calls Stop-CLIProxyAPI internally before launching a fresh process. All the same prerequisites apply (password check, version check), and the Auto Open WebUI setting is respected.

​
Single-instance enforcement

The tray application uses a Windows named mutex to prevent duplicate tray instances from running simultaneously: 
Mutex name: Global\CLIProxyAPI_Tray_SingleInstance
When the tray starts, it attempts to create this mutex. If the mutex already exists (meaning another tray instance is running), the new instance exits silently with no error dialog.
The single-instance mutex applies to the tray application itself, not to the CLIProxyAPI service process. The service is managed separately and can be started independently of the tray.

​
Process identification

The tray identifies the CLIProxyAPI process by name: 
Process name: cli-proxy-api
This is the name without the .exe extension, matched via PowerShell’s Get-Process -Name cli-proxy-api. If a process with this name is found, it is treated as the running CLIProxyAPI instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us