CLIProxyAPI Relay Toolkit

中文 | English

This is a generic Windows toolkit under the MIT License for running CLIProxyAPI locally, monitoring it continuously, and, when needed, exposing it to the public internet through a self-healing SSH reverse tunnel.

What This Repository Is

• A clean starting point for maintaining your own CLIProxyAPI deployment workflow on Windows
• A local-first toolkit that uses http://127.0.0.1:18317 as the primary endpoint in daily use
• A stable launcher + monitor design that does more than just start services and keeps lightweight status snapshots available
• An optional relay toolkit for users who also want a public endpoint

Core Capabilities

• Docker-based local CLIProxyAPI startup and shutdown
• WPF desktop launcher with buttons, step states, and runtime logs
• Background monitor that periodically writes local JSON status snapshots
• Visual status for Docker, local API, routing, SSH tunnel, and public endpoint
• Relay tunnel startup, repair, and supervision
• Automatic provider routing patching through the Management API
• Dedicated shell for git, pip, docker, and model downloads
• Bilingual docs and scripts

Recommended Architecture

To prioritize stability on Windows, this repository uses a layered design:

1. PowerShell handles the low-level control layer
2. WPF provides the UI shell
3. A background monitor provides lightweight status refresh
4. Scheduled Task on logon is used for autostart

Why this design:

• Docker Desktop is more stable in a logged-in user session than as a Windows Service
• SSH, browser launch, and local proxy interactions are easier to debug through PowerShell
• The monitor avoids running a full heavy probe on every UI refresh

How The Launcher + Monitor Work

• The monitor runs in the background and writes status snapshots into the run/ directory.
• The launcher reads local snapshots first, so the UI refresh feels much faster.
• Only when a snapshot is missing or stale does it trigger a heavier active probe.
• After start, restart, or repair, the launcher asks the monitor to sample again so the UI can catch up faster.

Repository Structure

• start-launcher.cmd Starts the desktop launcher.
• start-local-api.ps1 / stop-local-api.ps1 Manage the local Docker-based CLIProxyAPI.
• start-relay-tunnel.ps1 / stop-relay-tunnel.ps1 Manage the SSH reverse tunnel.
• start-relay-supervisor.ps1 / stop-relay-supervisor.ps1 Manage the relay supervisor.
• launcher/ Stores the launcher, monitor, build script, assets, and network guide.
• scripts/common.ps1 Shared config and secrets loading logic.
• config.example.yaml Public-safe CLIProxyAPI config template.
• secrets.local.example.txt Placeholder file for local API and management access.
• secrets.relay.example.txt Placeholder file for relay host and public endpoint settings.

Quick Start

1. Copy the example files.

Copy-Item .\config.example.yaml .\config.yaml
Copy-Item .\secrets.local.example.txt .\secrets.local.txt
Copy-Item .\secrets.relay.example.txt .\secrets.relay.txt
Copy-Item .\launcher\launcher.settings.example.json .\launcher\launcher.settings.json

2. Fill in the placeholders.

• config.yaml Your local CLIProxyAPI configuration.
• secrets.local.txt Fill in API_KEY and MANAGEMENT_KEY.
• secrets.relay.txt If you want a public endpoint, fill in the relay host, user, port, and public URL.
• launcher/launcher.settings.json Fill in the Docker Desktop path, local proxy, Clash controller, and routing preferences.

3. If you use relay mode, place your SSH private key.

• Default path: .\run\relay_ssh_ed25519

4. Start the toolkit.

.\start-launcher.cmd

Local-Only Mode And Relay Mode

If you only want local access:

• secrets.relay.txt can stay empty
• Use http://127.0.0.1:18317 directly
• The launcher will still work normally

If you also want a public endpoint:

• Fill in secrets.relay.txt
• Put the SSH private key into run/relay_ssh_ed25519
• Start the relay tunnel and supervisor through the launcher

Build The EXE

powershell -ExecutionPolicy Bypass -File .\launcher\build-launcher-exe.ps1

The build script uses ps2exe and installs it automatically if it is not already available for the current user.

Optional Autostart

powershell -ExecutionPolicy Bypass -File .\launcher\install-autostart.ps1

This registers a delayed “run on logon” task through Windows Scheduled Tasks.

To remove it:

powershell -ExecutionPolicy Bypass -File .\launcher\remove-autostart.ps1

Network Split

See launcher/NETWORK_GUIDE.md for practical suggestions covering:

• AI traffic
• GitHub traffic
• Package manager traffic
• Docker and model downloads
• Fallback rules for unknown traffic

Public Endpoint Path Reminder

When exposing an OpenAI-compatible endpoint publicly, make sure you use the /v1/... path.

• Correct: https://your-relay.example.com/v1/responses
• Wrong: https://your-relay.example.com/responses

License

This project is licensed under the MIT License.