Manual Location Setup

Manual Setup lets you use a CLI Proxy executable that you’ve downloaded yourself. This is useful when:

Auto Download fails or is blocked by your network
You need a specific version that isn’t the latest
You prefer to manage downloads manually
You already have CLI Proxy downloaded from a previous installation

Prerequisites

Before starting manual setup, download the CLI Proxy executable for your operating system:

Standard Version
Plus Version

Repository: router-for-me/CLIProxyAPIDownload: Latest ReleaseChoose the asset for your platform:

Windows: cli-proxy-api_windows_x64.zip
macOS (Intel): cli-proxy-api_darwin_x64.tar.gz
macOS (Apple Silicon): cli-proxy-api_darwin_arm64.tar.gz
Linux: cli-proxy-api_linux_x64.tar.gz

Repository: router-for-me/CLIProxyAPIPlusDownload: Latest ReleaseChoose the asset for your platform:

Windows: cli-proxy-api-plus_windows_x64.zip
macOS (Intel): cli-proxy-api-plus_darwin_x64.tar.gz
macOS (Apple Silicon): cli-proxy-api-plus_darwin_arm64.tar.gz
Linux: cli-proxy-api-plus_linux_x64.tar.gz

Plus Features:

GitHub Copilot support
Kiro login integration
Premium enhancements

Extract the Archive:

Windows: Right-click the .zip file and select “Extract All”
macOS/Linux: tar -xzf <filename>.tar.gz

Setup Steps

Launch Onboarding

On first launch, click Get Started on the welcome screen.

Select Manual Location

Choose Manual Location from the setup mode options.This option shows an amber folder icon and the description “Select your own downloaded CLI Proxy executable.”A file browser dialog will open immediately.

Browse for Executable

Navigate to where you extracted the CLI Proxy files and select the executable:Windows:

File: cli-proxy-api.exe or cli-proxy-api-plus.exe
Filter: Executable files (*.exe)

macOS/Linux:

File: cli-proxy-api or cli-proxy-api-plus
Make sure it has execute permissions: chmod +x cli-proxy-api

The file browser uses the native OS file picker, so the interface will match your operating system’s style.

After selecting the file, ZeroLimit will:

Store the executable path in settings
Set CLI Proxy mode to “manual”
Skip the version selection step (proceeds directly to management key)

Set Management Key

Enter a secret key to protect your CLI Proxy management API.What to enter:

New Installation
Existing Installation

If this is your first time setting up CLI Proxy:

Enter your desired secret key (e.g., my-secure-password)
Click Finish Setup

ZeroLimit will:

Create or update config.yaml in the same directory as the executable
Write your management key to the secret-key field
Configure the auth-dir path
Start the CLI Proxy server
Log you in automatically

If you already have CLI Proxy configured:

Find your existing config.yaml in the CLI Proxy directory
Open it and locate the secret-key value:
```
secret-key: "your-existing-key-here"
```
Enter that exact same key in the onboarding wizard
Click Finish Setup

ZeroLimit will use your existing configuration and log you in with the saved key.

The management key in ZeroLimit must match the secret-key in config.yaml, or authentication will fail.

Complete Setup

ZeroLimit automatically:

Updates config.yaml (if needed):
- Located in the same directory as the executable
- Reads config.example.yaml if config.yaml doesn’t exist
- Writes or updates the secret-key field
- Configures auth-dir to ~/.cli-proxy-api
Starts the server:
- Invokes the executable at the path you selected
- Waits for server startup
- Checks API health
Logs you in:
- API Base: http://localhost:8317
- Management Key: The key you entered
- Remember Credentials: Enabled

Success message: “CLI Proxy configuration complete!”

File Structure

After manual setup, your CLI Proxy directory should look like:

<your-chosen-location>/
├── cli-proxy-api(.exe)       # Executable you selected
├── config.yaml               # Configuration file (created/updated)
└── config.example.yaml       # Template (if included in release)

config.yaml example:

# CLI Proxy API Configuration

secret-key: "your-management-key"  # Must match ZeroLimit login
auth-dir: "C:\\Users\\YourName\\.cli-proxy-api"  # Windows
# auth-dir: "/home/username/.cli-proxy-api"  # Linux/macOS

server:
  host: 0.0.0.0
  port: 8317

# ... other configuration options

Configuration Process

The handleSetupKey function in OnboardingFlow.tsx:113-154 performs these operations:

Read existing config:

const proxyDir = await dirname(exePath);
const configPath = await join(proxyDir, 'config.yaml');
const exampleConfigPath = await join(proxyDir, 'config.example.yaml');

// Try config.yaml first, fall back to config.example.yaml
let configContent = '';
try {
  configContent = await readTextFile(configPath);
} catch {
  configContent = await readTextFile(exampleConfigPath);
}

Update secret-key:

// Replace existing secret-key lines
configContent = configContent.replace(
  /secret-key:\s*["'][^"']*["']/,
  `secret-key: "${managementKey}"`
);
configContent = configContent.replace(
  /secret-key:\s*$/m,
  `secret-key: "${managementKey}"`
);

Update auth-dir:

const homePath = await homeDir();
const authDir = `${homePath}\\.cli-proxy-api`.replace(/\\\\/g, '\\');
configContent = configContent.replace(
  /auth-dir:\s*.*$/,
  `auth-dir: "${authDir}"`
);

Write and start:

await writeTextFile(configPath, configContent);
const started = await startServer();

Troubleshooting

File Browser Cancellation

Symptom: File browser closes without selecting a file Behavior: You remain on the mode selection screen (step 2) Solution: Click Manual Location again to reopen the file browser

Selected Wrong File

Symptom: Selected a non-executable file or wrong version Solutions:

Go to Settings > CLI Proxy Server
Click Browse to select the correct executable
Restart ZeroLimit if needed

Error: “Authentication failed” after completing setup Causes:

Management key doesn’t match secret-key in config.yaml
config.yaml wasn’t created or updated properly
CLI Proxy server didn’t start

Solutions:

Verify config.yaml:

# Should contain:
secret-key: "the-exact-key-you-entered"

Check if server is running:
- Windows: Open Task Manager, look for cli-proxy-api.exe
- macOS/Linux: ps aux | grep cli-proxy-api

Manually start the server:

# Navigate to CLI Proxy directory
cd /path/to/cli-proxy

# Windows
.\cli-proxy-api.exe

# macOS/Linux
./cli-proxy-api

Watch for error messages in the console output

Verify config.yaml location:
- Must be in the same directory as the executable
- Filename must be exactly config.yaml (case-sensitive on Linux/macOS)

Server Won’t Start

Symptoms:

“Proxy failed to start” error
Health check fails
Port conflict errors

Solutions:

Check port availability:

Default port: 8317

Check if another service is using it:

# Windows
netstat -ano | findstr :8317

# macOS/Linux
lsof -i :8317

Run executable manually to see detailed errors:

cd /path/to/cli-proxy
./cli-proxy-api  # or cli-proxy-api.exe on Windows

Check permissions:
- macOS/Linux: chmod +x cli-proxy-api
- Windows: Right-click > Properties > Unblock (if file came from internet)
Try as administrator/root:
- Windows: Run ZeroLimit as Administrator
- Linux: sudo ./cli-proxy-api (not recommended for production)

config.yaml Not Found

Error: Cannot read config.yaml or config.example.yaml Causes:

Downloaded executable without accompanying files
Files extracted to different locations

Solutions:

Download complete release:
- Releases should include config.example.yaml
- Don’t download just the executable binary

Create config.yaml manually:

secret-key: "your-management-key"
auth-dir: "/path/to/.cli-proxy-api"

server:
  host: 0.0.0.0
  port: 8317

log:
  level: info

Save as config.yaml in the same directory as the executable

After Setup

Once manual setup is complete:

Your executable path is saved in ZeroLimit settings
CLI Proxy server is running on http://localhost:8317
You’re logged in and ready to configure providers

Provider Setup

Add and configure API providers

Server Settings

Manage executable path and auto-start

Auto Updates

Manually update to newer versions

Remote Server

Connect to a remote deployment instead

Changing Executable Path

To update the CLI Proxy executable path after initial setup:

Open ZeroLimit Settings
Navigate to CLI Proxy Server
Click Browse next to “Executable Path”
Select the new executable location
Restart the server for changes to take effect

This is useful when:

Upgrading to a new version
Moving files to a different directory
Switching between Standard and Plus versions

Getting Started

Features

Setup Guide

Configuration

Guides

Manual Location Setup

Prerequisites

Setup Steps

File Structure

Configuration Process

Troubleshooting

File Browser Cancellation

Selected Wrong File

Server Won’t Start

config.yaml Not Found

After Setup

Provider Setup

Server Settings

Auto Updates

Remote Server

Changing Executable Path

Build docs developers (and LLMs) love

Getting Started

Features

Setup Guide

Configuration

Guides

​Prerequisites

​Setup Steps

​File Structure

​Configuration Process

​Troubleshooting

​File Browser Cancellation

​Selected Wrong File

​Login Failed After Setup

​Server Won’t Start

​config.yaml Not Found

​After Setup

Provider Setup

Server Settings

Auto Updates

Remote Server

​Changing Executable Path

Build docs developers (and LLMs) love

Prerequisites

Setup Steps

File Structure

Configuration Process

Troubleshooting

File Browser Cancellation

Selected Wrong File

Login Failed After Setup

Server Won’t Start

config.yaml Not Found

After Setup

Changing Executable Path