# KushoAI Proxy Server

The KushoAI Proxy Server is a local Node.js application that enables seamless API testing when browser-based restrictions prevent direct API calls. This proxy serves as an alternative to the KushoAI Chrome extension, providing a robust solution for environments with strict security policies or when using non-Chromium browsers.

# Why Use the Proxy Server?

# CORS Restrictions and Browser Security

Modern web browsers implement Cross-Origin Resource Sharing (CORS) policies to prevent unauthorized cross-origin requests. When KushoAI attempts to make API calls directly from the browser, several security restrictions can block these requests:

# Browser Origin Limitations

Immutable Origin Header: Browsers automatically set the Origin header for all cross-origin requests and prevent JavaScript from overriding it
Security Enforcement: This browser-level security measure cannot be bypassed, ensuring that the origin of requests is always transparent to target servers
CORS Policy Blocking: If your target APIs don't include KushoAI's domain in their CORS policy, requests will be blocked by the browser

# Common Scenarios Requiring the Proxy

Corporate Networks: Organizations with strict CORS policies that don't allowlist external domains
Internal APIs: Backend services configured to only accept requests from specific origins
Development Environments: Local APIs that restrict cross-origin access
Non-Chromium Browsers: Browsers where the KushoAI Chrome extension cannot be installed

# How the Proxy Solves These Issues

The KushoAI Proxy Server operates as a local intermediary that:

Removes Origin Restrictions: Server-to-server requests don't include browser-imposed origin headers
Bypasses CORS Policies: Acts as a same-origin proxy, eliminating cross-origin request restrictions
Maintains Request Integrity: Preserves all request parameters, headers, and payloads while routing through the proxy
Enables Universal Testing: Works with any API regardless of its CORS configuration

# System Requirements

Node.js: Version 20.0 or higher
Operating System: Windows, macOS, or Linux
Network Access: Ability to reach target APIs from your local machine

# Installation Guide

# Step 1: Install Node.js (Recommended Method)

# Using Node Version Manager (NVM)

For macOS and Linux:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

For Windows:

Download and install nvm-windows from the official GitHub repository
Follow the installation wizard to complete setup

# Activate NVM

# Restart your terminal or reload your shell configuration
source ~/.bashrc  # or ~/.bash_profile depending on your shell

# Install and Configure Node.js

# Install Node.js version 20
nvm install 20

# Set Node.js 20 as the active version
nvm use 20

# Verify successful installation
node --version  # Should display v20.x.x
npm --version   # Should display npm version

# Step 2: Set Up the Proxy Server

# Clone the Repository

git clone https://github.com/kusho-co/kusho-proxy.git
cd kusho-proxy

# Install Dependencies

npm install

# Start the Proxy Server

node proxy.js

Success Indicators:

The proxy server will display startup messages in your terminal
Default proxy runs on http://localhost:3000 (unless configured otherwise)
The server remains active and ready to handle requests from KushoAI

# Configuration

# Connecting KushoAI to the Proxy

Once your proxy server is running, configure KushoAI to route API calls through the local proxy:

# Step 1: Access Settings

Navigate to Settings from the top-right menu in the KushoAI interface.

# Step 2: Enable Proxy Mode

Toggle the Enable Proxy option to route API calls through your local proxy server instead of using the Chrome extension.

# Step 3: Configure Proxy URL (Optional)

If you're running the proxy on a different port or hostname, update the proxy URL accordingly.

Default Configuration:

Host: localhost
Port: 3000
Protocol: http
Full URL: http://localhost:3000

# Usage and Testing

# Verifying Proxy Functionality

Start the Proxy: Ensure node proxy.js is running without errors
Configure KushoAI: Enable proxy mode in KushoAI settings
Execute Tests: Run your API tests through KushoAI - requests should now flow through the proxy
Monitor Logs: Check the proxy server terminal for request logging and any error messages

# Troubleshooting Common Issues

# Proxy Server Won't Start

Port Conflict: Another service may be using port 3000
Node.js Version: Ensure you're running Node.js 20 or higher
Dependencies: Run npm install to ensure all dependencies are installed

# API Calls Still Blocked

Proxy Configuration: Verify the proxy URL in KushoAI matches your running proxy server
Network Connectivity: Ensure your local machine can reach the target APIs
Firewall Settings: Check if local firewall rules are blocking the proxy

# Performance Considerations

Local Processing: All requests are processed locally, eliminating external network latency for the proxy step
Memory Usage: The proxy server has minimal memory footprint for typical API testing workloads
Concurrent Requests: Supports multiple simultaneous API calls without performance degradation

# Security Notes

Local Operation: The proxy server operates entirely on your local machine
No Data Storage: Requests and responses are not logged or stored persistently
Direct Routing: Acts as a pass-through proxy without modifying request content
Network Isolation: Only accessible from your local machine by default

The KushoAI Proxy Server provides a reliable, secure solution for API testing in environments where browser-based restrictions would otherwise prevent comprehensive testing workflows.