Remote HTTPS Server Connection

If you’re running CLI Proxy on a remote server or want to connect to an instance hosted elsewhere, you can skip the local setup and connect directly via HTTPS. This is useful for:

Connecting to a shared team CLI Proxy instance
Using a cloud-hosted proxy server
Accessing CLI Proxy from multiple devices
Separating the proxy server from the client application

Prerequisites

Before connecting to a remote server, you need:

Remote Server Running

A CLI Proxy server running on a remote host with:

Network accessibility from your location
HTTPS configured (strongly recommended for remote access)
Firewall rules allowing incoming connections

API Base URL

The full URL to your CLI Proxy server, for example:

https://llm.yourdomain.com
https://proxy.example.com:8317
http://192.168.1.100:8317 (local network only, not recommended for internet)

Management Key

The secret-key value from your remote server’s config.yaml file.Finding the key on the remote server:

# SSH into your remote server
ssh user@remote-host

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

# View the secret-key
grep secret-key config.yaml

Output:

secret-key: "your-secret-key-here"

Connection Steps

Skip Onboarding

When you first launch ZeroLimit, click Skip For Now on the welcome screen.This bypasses the local setup wizard and takes you directly to the login page.

Enter Connection Details

On the login page, fill in the form:API Base URL:

Enter the full URL to your remote server
Include the protocol (https:// or http://)
Include the port if non-standard (e.g., :8317)
Examples:
- https://proxy.mydomain.com
- https://llm.company.com:8317
- http://10.0.1.5:8317 (local network)

Management Key:

Enter the secret-key from the remote server’s config.yaml
This is the authentication credential
Must match exactly (case-sensitive)

Remember Credentials (optional):

Check this box to save your credentials securely
You’ll stay logged in across app restarts
Credentials are encrypted in local storage

Only enable “Remember Credentials” on devices you trust. The management key grants full access to your CLI Proxy instance.

Click the Login button to connect.ZeroLimit will:

Normalize the API base URL (adds /v0/management path)
Send an authentication request to the management API
Fetch the server configuration and validate access
Update connection status to “connected”
Store credentials if “Remember” is checked

Success: You’ll be redirected to the dashboardFailure: An error message will appear (see Troubleshooting below)

Verify Connection

After successful login, verify your connection:

Dashboard should show server status and version
Connection indicator should be green/connected
You should see your configured providers (if any)

The top bar displays:

Server version (e.g., “v1.2.3”)
Connection status: “Connected” in green

API URL Normalization

ZeroLimit automatically normalizes the API base URL you enter: Input examples:

https://proxy.example.com
https://proxy.example.com/
https://proxy.example.com/v0/management
https://proxy.example.com/v0/management/

Normalized to:

https://proxy.example.com

The management API path (/v0/management) is appended automatically when making requests. Implementation (auth.store.ts:80):

const apiBase = normalizeApiBase(credentials.apiBase);
apiClient.setConfig({ apiBase, managementKey });

Connection Lifecycle

Initial Connection

User enters credentials on login page

Set connecting status:

set({ connectionStatus: 'connecting' });

Configure API client:

apiClient.setConfig({ apiBase, managementKey });

Fetch server config (auth.store.ts:87):

await useConfigStore.getState().fetchConfig(true);

Update state on success:

set({
  isAuthenticated: true,
  apiBase,
  managementKey,
  rememberPassword,
  connectionStatus: 'connected',
  connectionError: null,
});

Session Restoration

If “Remember Credentials” was enabled, ZeroLimit automatically restores your session on launch:

Load saved credentials from secure storage
Normalize API base URL
Configure API client
Attempt auto-login
Success: Continue to dashboard
Failure: Show login page

Connection Monitoring

ZeroLimit monitors connection health:

Health checks: Periodic API pings to verify server availability
Network errors: Detected via failed requests
Unauthorized: Server rejects management key

Event listeners (auth.store.ts:188-202):

window.addEventListener('unauthorized', () => {
  useAuthStore.getState().logout();
});

window.addEventListener('network-error', () => {
  useAuthStore.getState().updateConnectionStatus(
    'disconnected',
    'Network error or server unreachable'
  );
});

HTTPS Configuration

For remote access, HTTPS is strongly recommended.

Why HTTPS?

Encryption: Protects your management key in transit
Authentication: Verifies server identity
Security: Prevents man-in-the-middle attacks

Setting up HTTPS on the Server

Reverse Proxy (Recommended)
Self-Signed Certificate
Let's Encrypt

Use a reverse proxy like Nginx or Caddy to handle HTTPS:Nginx example:

server {
  listen 443 ssl http2;
  server_name proxy.yourdomain.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:8317;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Caddy example (auto HTTPS):

proxy.yourdomain.com {
  reverse_proxy localhost:8317
}

For testing or internal use, you can use a self-signed certificate:

Generate certificate:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

Configure CLI Proxy (if it supports direct HTTPS)
Trust certificate on client:
- Windows: Import to Trusted Root Certification Authorities
- macOS: Add to Keychain and trust
- Linux: Add to /usr/local/share/ca-certificates/ and run update-ca-certificates

Self-signed certificates show security warnings. Only use for testing or trusted internal networks.

For internet-facing servers, use Let’s Encrypt for free certificates:With Certbot:

sudo certbot --nginx -d proxy.yourdomain.com

With Caddy: Caddy automatically obtains and renews Let’s Encrypt certificates. No configuration needed!

Troubleshooting

Connection Failed

Error: “Connection failed” or network timeout Causes:

Server is not running
Firewall blocking access
Incorrect URL
Network issues

Solutions:

Verify server is running:

# On the server
systemctl status cli-proxy-api  # if using systemd
# or
ps aux | grep cli-proxy-api

Test connectivity:

# From your local machine
curl -v https://proxy.yourdomain.com/v0/management/health

Check firewall rules:

# Allow port 8317 (or your configured port)
sudo ufw allow 8317/tcp  # Ubuntu/Debian
sudo firewall-cmd --add-port=8317/tcp --permanent  # CentOS/RHEL

Verify DNS resolution:

nslookup proxy.yourdomain.com
ping proxy.yourdomain.com

Authentication Failed

Error: “Login failed” or “Authentication failed” Causes:

Incorrect management key
Key mismatch between client and server

Solutions:

Verify secret-key on server:

ssh user@remote-host
cat /path/to/cli-proxy-api/config.yaml | grep secret-key

Check for whitespace:
- Secret keys are trimmed in ZeroLimit: .trim()
- Ensure no extra spaces in config.yaml

Update server config if needed:

secret-key: "new-key-here"

Then restart CLI Proxy:

systemctl restart cli-proxy-api

SSL/TLS Errors

Error: “SSL certificate error” or “Certificate validation failed” Causes:

Self-signed certificate not trusted
Expired certificate
Certificate domain mismatch

Solutions:

For self-signed certificates:
- Import the certificate to your OS trust store
- Or use HTTP for testing (not recommended for production)
For expired certificates:
- Renew with Let’s Encrypt: certbot renew
- Or generate new self-signed certificate
For domain mismatch:
- Ensure URL matches certificate CN/SAN
- Access via correct domain name, not IP address

Frequent Disconnections

Symptoms: Connection drops and reconnects repeatedly Causes:

Unstable network
Server restarting
Firewall timeout

Solutions:

Check server logs for crashes or restarts
Adjust firewall timeout settings
Use a more stable network connection
Check server resource usage (CPU, memory, disk)

Can’t Access from Other Devices

Symptoms: Can’t connect from other computers/locations Causes:

Firewall blocking external access
Server only listening on localhost
Port forwarding not configured

Solutions:

Configure server to listen on all interfaces (config.yaml):

server:
  host: 0.0.0.0  # Not 127.0.0.1
  port: 8317

Open firewall for external access:

sudo ufw allow from any to any port 8317 proto tcp

Configure port forwarding if behind NAT
Use a reverse proxy with proper HTTPS (recommended)

Security Best Practices

Remote access exposes your CLI Proxy to the internet. Follow these security practices.

Always use HTTPS for remote connections
Use strong management keys:
- At least 16 characters
- Mix of letters, numbers, symbols
- Generate with: openssl rand -base64 24

Restrict access with firewall rules:

# Only allow specific IPs
sudo ufw allow from 203.0.113.5 to any port 8317

Monitor access logs for unauthorized attempts
Rotate keys periodically
Use VPN for additional security layer
Keep software updated to patch security vulnerabilities

After Connection

Once connected to a remote server:

Provider Management

Configure providers on the remote server

Monitoring Usage

Monitor server health and usage

Managing Proxy

Start, stop, and configure the proxy

Troubleshooting

Common issues and solutions

Switching to Local Setup

If you later want to set up a local CLI Proxy instance:

Logout from the remote server
Open Settings > CLI Proxy Server
Configure local executable path
Restart ZeroLimit
Login with http://localhost:8317 and local management key

You can switch between local and remote connections as needed by changing the API Base URL on the login page.

Getting Started

Features

Setup Guide

Configuration

Guides

Remote HTTPS Server Connection

Prerequisites

Connection Steps

API URL Normalization

Connection Lifecycle

Initial Connection

Session Restoration

Connection Monitoring

HTTPS Configuration

Why HTTPS?

Setting up HTTPS on the Server

Troubleshooting

Connection Failed

Authentication Failed

SSL/TLS Errors

Frequent Disconnections

Can’t Access from Other Devices

Security Best Practices

After Connection

Provider Management

Monitoring Usage

Managing Proxy

Troubleshooting

Switching to Local Setup

Build docs developers (and LLMs) love

Getting Started

Features

Setup Guide

Configuration

Guides

​Prerequisites

​Connection Steps

​API URL Normalization

​Connection Lifecycle

​Initial Connection

​Session Restoration

​Connection Monitoring

​HTTPS Configuration

​Why HTTPS?

​Setting up HTTPS on the Server

​Troubleshooting

​Connection Failed

​Authentication Failed

​SSL/TLS Errors

​Frequent Disconnections

​Can’t Access from Other Devices

​Security Best Practices

​After Connection

Provider Management

Monitoring Usage

Managing Proxy

Troubleshooting

​Switching to Local Setup

Build docs developers (and LLMs) love

Prerequisites

Connection Steps

API URL Normalization

Connection Lifecycle

Initial Connection

Session Restoration

Connection Monitoring

HTTPS Configuration

Why HTTPS?

Setting up HTTPS on the Server

Troubleshooting

Connection Failed

Authentication Failed

SSL/TLS Errors

Frequent Disconnections

Can’t Access from Other Devices

Security Best Practices

After Connection

Switching to Local Setup