🌈 Introduction

Warning

This project is currently under active development. Documentation may not reflect the latest changes. If you encounter unexpected behavior, please consider using a previous stable version or report issues on our GitHub repository.

🌟 Core Capabilities

📥 Quick Start

One-Click Deployment (No Fuss, No Muss!)

Note

NyaProxy automatically creates a basic working configuration when it starts. You just need to access the/config endpoint to add your API keys!

Tip

You can use Gemini AI Studio to get a free API key for testing. Gemini's API is OpenAI-compatible and works seamlessly with NyaProxy.Get a Gemini API key here.

Local Deployment (For the DIY Enthusiasts!)

Prerequisites

Installation

1. Install from PyPI (the easiest way!)

pip install nya-proxy

2. Run NyaProxy

nyaproxy

nyaproxy --config config.yaml

3. Verify Your Setup

Important

If you expose this proxy to the internet, make sure to set a strong API key in your configuration to prevent unauthorized access. The first key in your API keys array will be used as the master key for accessing sensitive interfaces like the dashboard and configuration UI, while additional keys can be used for regular API requests only.

If no master API key is specified, no login page will be shown and anyone can access the dashboard and configuration UI. This is convenient for local testing but not recommended for production environments.

Detailed Deployment Guides

Install from Source

# Clone the repositorygit clone https://github.com/Nya-Foundation/nyaproxy.gitcd nyaproxy# Install dependenciespip install -e.# Run NyaProxynyaproxy

Docker

docker run -d \  -p 8080:8080 \# -v ${PWD}/config.yaml:/app/config.yaml \# -v ${PWD}/app.log:/app/app.log \  k3scat/nya-proxy:latest

Configuration

# NyaProxy Configuration File# This file contains server settings and API endpoint configurationsserver:api_key:logging:enabled:truelevel:debuglog_file:app.logproxy:enabled:falseaddress:socks5://username:password@proxy.example.com:1080dashboard:enabled:truecors:# Allow all origins with "*", but specify exact origins when allow_credentials is true for securityallow_origins:["*"]allow_credentials:trueallow_methods:["GET", "POST", "PUT", "DELETE", "OPTIONS"]allow_headers:["*"]# Default configuration applied to all API endpoints unless overriddendefault_settings:key_variable:keyskey_concurrency:true# mark it as true if each key can handle multiple concurrent requests, otherwise the key will be locked until the request completesrandomness:0.0# Random delay of (0.0-x)s to introduce variability in request timing and avoid detection due to consistent request patterns due to rate limitsload_balancing_strategy:round_robin# Path and method filteringallowed_paths:enabled:false# Set to true to enable request path filteringmode:whitelist# if "whitelist", only allow listed paths; if "blacklist", block listed pathspaths:      -"*"allowed_methods:["GET", "POST", "PUT", "DELETE", "OPTIONS"]# Allowed HTTP methods for the APIqueue:max_size:200max_workers:10# Maximum number of concurrent workers for processing requestsexpiry_seconds:300rate_limit:enabled:trueendpoint_rate_limit:10/s# Default endpoint rate limit - can be overridden per APIkey_rate_limit:10/m# Default key rate limit - can be overridden per APIip_rate_limit:5000/d# IP-based rate limit to protect against abuse and key redistributionuser_rate_limit:5000/d# User-based rate limit per proxy API key defined in server sectionrate_limit_paths:       -"*"retry:enabled:truemode:key_rotationattempts:3retry_after_seconds:1retry_request_methods:[ POST, GET, PUT, DELETE, PATCH, OPTIONS ]retry_status_codes:[ 429, 500, 502, 503, 504 ]timeouts:request_timeout_seconds:300apis:gemini:# Example for OpenAI-compatible API endpointname:Google Gemini API# Supported endpoints:# Gemini: https://generativelanguage.googleapis.com/v1beta/openai# OpenAI: https://api.openai.com/v1# Anthropic: https://api.anthropic.com/v1# DeepSeek: https://api.deepseek.com/v1# Mistral: https://api.mistral.ai/v1# OpenRouter: https://api.openrouter.ai/v1# Ollama: http://localhost:11434/v1endpoint:https://generativelanguage.googleapis.com/v1beta/openaialiases:    -/geminikey_variable:keysheaders:Authorization:'Bearer ${{keys}}'variables:keys:      -your_gemini_key_1      -your_gemini_key_2      -your_gemini_key_3load_balancing_strategy:least_requestsrate_limit:enabled:true# For Gemini-2.5-pro-exp-03-25, rate limits per key are 5 RPM and 25 RPD# Endpoint rate limit should be n × per-key-RPD, where n is the number of keysendpoint_rate_limit:75/dkey_rate_limit:5/m# Paths to apply rate limits (regex supported) - defaults to all paths "*"rate_limit_paths:        -"/chat/*"        -"/images/*"# Request body substitution settingsrequest_body_substitution:enabled:false# Substitution rules for request body with JMEPathrules:# Since Gemini API doesn't support frequency_penalty and presence_penalty, we remove them with these rules        -name:"Remove frequency_penalty"operation:removepath:"frequency_penalty"conditions:            -field:"frequency_penalty"operator:"exists"        -name:"Remove presence_penalty"operation:removepath:"presence_penalty"conditions:            -field:"presence_penalty"operator:"exists"test:name:Test APIendpoint:http://127.0.0.1:8082key_variable:keysrandomness:5headers:Authorization:'Bearer ${{keys}}'User-Agent:${{agents}}# flexible headers customization with template variables supportedvariables:keys:      -your_test_key_1      -your_test_key_2      -your_test_key_3agents:      -test_agent_1      -test_agent_2      -test_agent_3load_balancing_strategy:least_requestsrate_limit:enabled:trueendpoint_rate_limit:20/mkey_rate_limit:5/mip_rate_limit:5000/duser_rate_limit:5000/drate_limit_paths:        -"/v1/*"# feel free to add more APIs here, just follow the same structure as above

📡 Service Endpoints

Note

Replace8080 andlocalhost with your configured port and host setting if different

🔧 API Configuration

OpenAI-Compatible APIs (Gemini, Anthropic, etc)

gemini:name:Google Gemini APIendpoint:https://generativelanguage.googleapis.com/v1beta/openaialiases:    -/geminikey_variable:keysheaders:Authorization:'Bearer ${{keys}}'variables:keys:      -your_gemini_key_1      -your_gemini_key_2load_balancing_strategy:least_requestsrate_limit:endpoint_rate_limit:75/d# Total endpoint limitkey_rate_limit:5/m# Per-key limitrate_limit_paths:      -"/chat/*"# Apply limits to specific paths      -"/images/*"

Generic REST APIs

novelai:name:NovelAI APIendpoint:https://image.novelai.netaliases:    -/novelaikey_variable:tokensheaders:Authorization:'Bearer ${{tokens}}'variables:tokens:      -your_novelai_token_1      -your_novelai_token_2load_balancing_strategy:round_robinrate_limit:endpoint_rate_limit:10/skey_rate_limit:2/s

🔒 Security Features

Multiple API Keys Support

server:api_key:     -your_master_key_for_admin_access    -another_api_key_for_proxy_only    -yet_another_api_key_for_proxy_only

Tip

The first key in the list acts as the master key with full access to the dashboard and configuration UI. Additional keys can only be used for API proxy requests. This enables you to share limited access with different teams or services.

Caution

When sharing your NyaProxy instance, never share your master key. Instead, create additional keys for different users or applications.

Advanced Features

🚦 Rate Limiting Capabilities

rate_limit_paths:  -"/chat/*"# Only limit chat endpoints  -"/images/*"# Only limit image generation  -"/v1/models"# Limit specific endpoint

🔄 Dynamic Header Substitution

apis:my_api:headers:Authorization:'Bearer ${{keys}}'X-Custom-Header:'${{custom_variables}}'variables:keys:        -key1        -key2custom_variables:        -value1        -value2

Note

Variables in headers are automatically substituted with values from your variables list, following your configured load balancing strategy.

🔧 Request Body Substitution

request_body_substitution:enabled:truerules:    -name:"Default to GPT-4"operation:setpath:"model"value:"gpt-4"conditions:        -field:"model"operator:"exists"

🖥️ Management Interfaces

Real-time Metrics Dashboard

Visual Configuration Interface

❤️ Community

Note

Need support? Contactk3scat@gmail.com or join our discord community atNya Foundation

📈 Project Growth