Marc Rejohn Castillano 5cb6561924 added ruflo

2026-04-09 19:01:53 +08:00

11 KiB

Raw Blame History

Standalone Proxy Mode - Use Gemini/OpenRouter with Claude Code & Cursor

Overview

The standalone proxy allows you to use Gemini or OpenRouter models with tools that expect the Anthropic API, such as:

✅ Claude Code (Anthropic's official CLI)
⏳ Cursor IDE (when ANTHROPIC_BASE_URL support is added)
✅ Any tool that supports ANTHROPIC_BASE_URL

Cost Savings: 85-90% cheaper than direct Anthropic API!

Quick Start

Start Gemini Proxy (Default)

# Set your API key
export GOOGLE_GEMINI_API_KEY=your-key-here

# Start proxy server
npx agentic-flow@1.1.11 proxy

Start OpenRouter Proxy

# Set your API key
export OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Start proxy server
npx agentic-flow@1.1.11 proxy --provider openrouter --model "openai/gpt-4o-mini"

Usage with Claude Code

Claude Code officially supports custom proxy URLs via ANTHROPIC_BASE_URL.

Terminal 1: Start Proxy

# Gemini
export GOOGLE_GEMINI_API_KEY=your-key-here
npx agentic-flow proxy

# OR OpenRouter
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
npx agentic-flow proxy --provider openrouter

Terminal 2: Use Claude Code

# Point Claude Code to the proxy
export ANTHROPIC_BASE_URL=http://localhost:3000
export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key  # Any value works

# Now use Claude Code normally
claude

# Or with direct commands
claude --agent coder --task "Create a REST API in Python"

That's it! Claude Code will now route all requests through the proxy, using Gemini or OpenRouter instead of Anthropic.

Usage with Cursor IDE

Status: Cursor does not currently support custom ANTHROPIC_BASE_URL for Anthropic models.

Workaround: Use this feature request: https://github.com/cursor/cursor/issues/1604

Once Cursor adds support, usage will be:

# Start proxy
export GOOGLE_GEMINI_API_KEY=your-key-here
npx agentic-flow proxy

# Configure Cursor
Settings → API Keys
  Anthropic Base URL: http://localhost:3000
  Anthropic API Key: sk-ant-proxy-dummy-key

Full Command Reference

Start Proxy

npx agentic-flow proxy [OPTIONS]

Options

Option	Short	Description	Default
`--provider`	`-p`	Provider (gemini, openrouter)	gemini
`--port`	`-P`	Port number	3000
`--model`	`-m`	Model to use (provider-specific)	Auto
`--help`	`-h`	Show help	-

Environment Variables

Variable	Required For	Description
`GOOGLE_GEMINI_API_KEY`	Gemini	Your Google Gemini API key
`OPENROUTER_API_KEY`	OpenRouter	Your OpenRouter API key
`COMPLETION_MODEL`	Optional	Override default model

Examples

Example 1: Gemini with Custom Port

export GOOGLE_GEMINI_API_KEY=AIza...
npx agentic-flow proxy --port 8080

# In another terminal
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
claude

Example 2: OpenRouter with Specific Model

export OPENROUTER_API_KEY=sk-or-v1-...
npx agentic-flow proxy --provider openrouter --model "anthropic/claude-3.5-sonnet"

# Use Claude Code
export ANTHROPIC_BASE_URL=http://localhost:3000
export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
claude --agent researcher --task "Analyze market trends"

Example 3: Gemini with DeepSeek via OpenRouter

export OPENROUTER_API_KEY=sk-or-v1-...
npx agentic-flow proxy --provider openrouter --model "deepseek/deepseek-chat-v3.1"

# 98% cost savings vs Claude Sonnet!
export ANTHROPIC_BASE_URL=http://localhost:3000
export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
claude --agent coder --task "Build a web scraper"

Supported Models

Gemini Models (via Google Gemini API)

Default: gemini-2.0-flash-exp

Available models:

gemini-2.0-flash-exp - Fast, experimental, free tier
gemini-1.5-pro - High quality, paid
gemini-1.5-flash - Fast, cheap

OpenRouter Models (via OpenRouter API)

Default: meta-llama/llama-3.1-8b-instruct

Popular models:

openai/gpt-4o-mini - Fast, cheap OpenAI model ($0.15/1M tokens)
anthropic/claude-3.5-sonnet - Claude via OpenRouter (same model, lower cost)
deepseek/deepseek-chat-v3.1 - 98% cheaper than Claude ($0.014/1M tokens)
meta-llama/llama-3.3-70b-instruct - OSS, very cheap
google/gemini-2.0-flash-exp - Gemini via OpenRouter

See full list: https://openrouter.ai/models

How It Works

┌─────────────────┐
│   Claude Code   │
│   or Cursor     │
└────────┬────────┘
         │ ANTHROPIC_BASE_URL=http://localhost:3000
         │ Anthropic API format requests
         ▼
┌─────────────────────────┐
│  Agentic Flow Proxy     │
│  (Port 3000)            │
│  ┌─────────────────┐    │
│  │ API Translator  │    │
│  │ Anthropic →     │    │
│  │ Gemini/OpenRouter│   │
│  └─────────────────┘    │
└────────┬────────────────┘
         │ Gemini/OpenRouter API format
         ▼
┌─────────────────┐
│ Gemini API      │ OR ┌─────────────────┐
│ or              │    │ OpenRouter API  │
│ OpenRouter      │    └─────────────────┘
└─────────────────┘

Translation:

Claude Code sends Anthropic API request to proxy
Proxy translates to Gemini/OpenRouter format
Provider API returns response
Proxy translates back to Anthropic format
Claude Code receives response as if from Anthropic

Cost Comparison

Provider	Model	Cost per 1M tokens (input)	Savings vs Anthropic
Anthropic	Claude Sonnet 4.5	$3.00	Baseline
Gemini (proxy)	gemini-2.0-flash-exp	$0.00 (free tier)	100% 🎉
OpenRouter (proxy)	gpt-4o-mini	$0.15	95%
OpenRouter (proxy)	deepseek-chat-v3.1	$0.014	98%

Real Example:

Task: Generate 10,000 lines of code (500K tokens)
Anthropic Claude Sonnet 4.5: $1.50
Gemini (free tier): $0.00
OpenRouter (DeepSeek): $0.007

Features

MCP Tools Support (v1.1.11+)

MCP tools now work through the proxy! Enable with:

# Start proxy
export GOOGLE_GEMINI_API_KEY=your-key-here
npx agentic-flow proxy

# Enable MCP in Claude Code
export ENABLE_CLAUDE_FLOW_SDK=true
export ANTHROPIC_BASE_URL=http://localhost:3000
export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key

# MCP tools will be forwarded to Gemini/OpenRouter
claude --agent coder --task "Use memory_store to save config"

All 7 MCP tools work:

memory_store - Persistent memory
memory_retrieve - Retrieve memory
memory_search - Search memory
swarm_init - Initialize agent swarm
agent_spawn - Spawn agents
task_orchestrate - Orchestrate tasks
swarm_status - Get swarm status

Rate Limits

Gemini Free Tier:

10 requests per minute
50 requests per day

OpenRouter:

Varies by model
Most models: 100+ req/min
Free models may have limits

Workaround for Gemini limits: Use OpenRouter for higher throughput.

Troubleshooting

Proxy not starting

# Check if port is in use
lsof -ti:3000

# Use different port
npx agentic-flow proxy --port 8080

Claude Code hanging

# Verify proxy is running
curl http://localhost:3000/health

# Should return: {"status":"ok","service":"anthropic-to-gemini-proxy"}

API key errors

# Verify key is set
echo $GOOGLE_GEMINI_API_KEY
echo $OPENROUTER_API_KEY

# Re-export if needed
export GOOGLE_GEMINI_API_KEY=your-key-here

Wrong model being used

# Check proxy logs for model selection
# Proxy prints model on startup

# Override with --model flag
npx agentic-flow proxy --provider openrouter --model "openai/gpt-4o-mini"

Advanced Configuration

Custom .env File

Create .env in your project:

# .env
GOOGLE_GEMINI_API_KEY=AIza...
OPENROUTER_API_KEY=sk-or-v1-...
COMPLETION_MODEL=gemini-2.0-flash-exp
PROXY_PORT=3000

Then start proxy:

npx agentic-flow proxy  # Reads .env automatically

Run Proxy in Background

# Linux/Mac
npx agentic-flow proxy &

# Or with nohup for persistence
nohup npx agentic-flow proxy > proxy.log 2>&1 &

# Check if running
ps aux | grep agentic-flow

# Stop
pkill -f agentic-flow

Docker Deployment

FROM node:22-slim

RUN npm install -g agentic-flow@1.1.11

EXPOSE 3000

CMD ["npx", "agentic-flow", "proxy", "--provider", "gemini"]

docker build -t agentic-flow-proxy .
docker run -d -p 3000:3000 -e GOOGLE_GEMINI_API_KEY=your-key agentic-flow-proxy

Security Considerations

Local Network Only

By default, proxy binds to all interfaces (0.0.0.0). For security:

# TODO: Add --host option to bind to localhost only
# Currently: Proxy listens on all interfaces

Workaround: Use firewall rules to restrict access.

API Key Protection

Never commit .env files to version control
Use environment variables in CI/CD
Rotate keys regularly

HTTPS/TLS

Currently, proxy runs on HTTP (localhost). For production:

Use reverse proxy (nginx, Caddy) with TLS
Or use cloud deployment with built-in TLS (Cloudflare, AWS)

FAQ

Q: Can I use this with other tools besides Claude Code? A: Yes! Any tool that supports ANTHROPIC_BASE_URL environment variable will work.

Q: Does this work with streaming responses? A: Yes, streaming is fully supported for both Gemini and OpenRouter.

Q: Can I use multiple proxies simultaneously? A: Yes, just use different ports:

# Terminal 1: Gemini on 3000
npx agentic-flow proxy --port 3000

# Terminal 2: OpenRouter on 3001
npx agentic-flow proxy --provider openrouter --port 3001

Q: Will Cursor support this? A: Not yet. Track progress: https://github.com/cursor/cursor/issues/1604

Q: Can I contribute other provider proxies? A: Yes! See /src/proxy/anthropic-to-*.ts for examples. PRs welcome for AWS Bedrock, Azure, etc.

What's Next

Planned Features

--host option to bind to localhost only
Built-in TLS/HTTPS support
Prometheus metrics endpoint
Request/response logging
Multi-provider load balancing
AWS Bedrock proxy
Azure OpenAI proxy

MCP Proxy Validation - MCP tool forwarding details
v1.1.11 Release Notes - What's new
Claude Code Docs - Official Claude Code guide

Support

GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
Discord: (coming soon)
Twitter: @rUv

Published: 2025-10-05 Version: 1.1.11 Status: Production Ready ✅

11 KiB Raw Blame History