Bypass geographic blocks, protect your identity, and route AI traffic through any proxy — with zero configuration complexity.

---

Why Use Proxies?
• Architecture Overview
• 3-Level Proxy System
• Proxy Registry (CRUD)
• 1proxy Free Marketplace
• Proxy Rotation
• Anti-Detection & Stealth
• Upstream Proxy Modes
• Dashboard UI
• API Reference
• Environment Variables
• Troubleshooting

---

Russia, China, Iran, Cuba, Turkey, and other countries encounter errors like:

Geographic bypass
IP rotation
Privacy
Compliance
Testing

---

Proxy Registry
Proxy Dispatcher		ProxyAgent/SOCKS dispatchers with caching
Proxy Fetch		with proxy dispatcher injection
Settings Route
Management Route
1proxy DB
1proxy Sync
1proxy Rotator

---

four independent scopes, resolved in priority order:

which checks each level in order:

Account-level — Is there a proxy assigned to this specific connection ID?
1. Provider-level — Is there a proxy assigned to this provider (e.g., )?
2. Global-level — Is there a global proxy configured?
3. No proxy — Direct connection to the provider.

		requests

---

) that stores all your proxies. Each proxy has:

		, ,
		or
		or

Via Dashboard:

Settings → Proxy
1. Add Proxy

Via API:

curl -X POST http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US Proxy",
    "type": "http",
    "host": "proxy.example.com",
    "port": 8080,
    "username": "user",
    "password": "pass",
    "region": "US"
  }'

curl -X PATCH http://localhost:20128/api/v1/management/proxies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "proxy-uuid-here",
    "host": "new-proxy.example.com",
    "port": 9090
  }'

Note: Credentials are preserved unless you explicitly send non-empty replacements. Sending empty strings for / will keep the stored values.

# Fails if proxy is assigned to any scope
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid"

# Force delete (removes assignments too)
curl -X DELETE "http://localhost:20128/api/v1/management/proxies?id=proxy-uuid&force=1"

curl "http://localhost:20128/api/v1/management/proxies?limit=50&offset=0"

# Assign to global scope
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "global", "proxy": {"type":"http","host":"proxy.example.com","port":8080}}'

# Assign to a specific provider
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "provider", "id": "openai", "proxy": {"type":"socks5","host":"socks.example.com","port":1080}}'

# Assign to a specific connection/key
curl -X PUT http://localhost:20128/api/settings/proxy \
  -H "Content-Type: application/json" \
  -d '{"level": "key", "id": "connection-uuid", "proxy": {"type":"http","host":"key-proxy.com","port":3128}}'

curl "http://localhost:20128/api/settings/proxy?resolve=connection-uuid"

, , or ) and source.

curl -X POST http://localhost:20128/api/v1/management/proxies/bulk-assign \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "provider",
    "scopeIds": ["openai", "anthropic", "codex"],
    "proxyId": "proxy-uuid"
  }'

Backup/Restore system. When you export your OmniRoute configuration:

Dashboard → Settings → Backup
1. Export — proxy registry and assignments are included
2. Import and upload the backup file

upsert by host+port — if you import a proxy that already exists (same host and port), it updates instead of creating a duplicate.

to re-run.

---

Contributed by @oyi77 — PR #1847 (Issue #1788)

1proxy community platform to provide access to hundreds of free, validated proxies from around the world. This is perfect for users who don't have their own proxy infrastructure.

Sync — OmniRoute fetches validated proxies from the 1proxy API
1. Store — Proxies are saved in the same table with
2. Filter — Filter by protocol, country, quality score
3. Rotate — Pick the best proxy using quality, random, or sequential strategies
4. Auto-degrade — Failed proxies get their quality score reduced; below threshold → marked inactive

Via Dashboard:

Settings → 1proxy tab
1. "Sync Now"

Via API:

# Trigger sync
curl -X POST http://localhost:20128/api/settings/oneproxy \
  -H "Content-Type: application/json" \
  -d '{}'

# Response:
# { "success": true, "added": 127, "updated": 45, "failed": 2, "total": 172 }

# Filter by protocol
curl "http://localhost:20128/api/settings/oneproxy?protocol=socks5"

# Filter by country
curl "http://localhost:20128/api/settings/oneproxy?countryCode=US"

# Filter by minimum quality score
curl "http://localhost:20128/api/settings/oneproxy?minQuality=80"

# Combine filters
curl "http://localhost:20128/api/settings/oneproxy?protocol=http&countryCode=DE&minQuality=70"

	, , or

Failed requests reduce the score by 10 points
• Score drops to ≤10 → proxy is marked

# Rotate by quality (best proxy first) — default
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -H "Content-Type: application/json" \
  -d '{"strategy": "quality"}'

# Random rotation
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "random"}'

# Sequential (least recently validated first)
curl -X POST http://localhost:20128/api/settings/oneproxy/rotate \
  -d '{"strategy": "sequential"}'

5 consecutive sync failures, further sync attempts are blocked
• or restart the server

# Delete a single 1proxy proxy
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?id=proxy-uuid"

# Clear ALL 1proxy proxies (manual proxies are untouched)
curl -X DELETE "http://localhost:20128/api/settings/oneproxy?clearAll=1"

---

to generate browser-like TLS fingerprints, bypassing bot detection systems that flag non-browser TLS handshakes.

CLI Fingerprint Toggle () reorders HTTP headers and JSON body fields to match the exact signature of native CLI binaries (Claude Code, Codex, etc.). This works on top of the proxy:

IP masking and request authenticity simultaneously.

---

curl -X PUT "http://localhost:20128/api/upstream-proxy/openai" \
  -H "Content-Type: application/json" \
  -d '{"mode": "native", "enabled": true}'

---

Global proxy configuration (set once for all traffic)
• Per-provider proxy overrides
• Per-connection proxy assignments
• Connection test through configured proxy
• Color-coded badges showing active proxy level

Sync Now button to fetch free proxies
• Stats cards: Total, Active, Avg Quality, Last Sync
• Filters: Protocol, Country Code, Min Quality
• Proxy table with host, protocol, country, quality score, latency, anonymity, Google access
• Sync status panel with success/failure tracking and consecutive failure count
• Clear All to remove all 1proxy entries

---

---

---

in your file and restart.

)
• )

before starting the OAuth flow. OmniRoute routes OAuth token exchange through the configured proxy. Set a global or provider-level proxy first, then connect.

1. is (not )

curl "http://localhost:20128/api/settings/oneproxy?action=status"

, the circuit breaker has tripped. Restart the server to reset, or wait for manual reset.

---

Table

CREATE TABLE proxy_registry (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  type TEXT NOT NULL DEFAULT 'http',
  host TEXT NOT NULL,
  port INTEGER NOT NULL,
  username TEXT DEFAULT '',
  password TEXT DEFAULT '',
  region TEXT,
  notes TEXT,
  status TEXT DEFAULT 'active',
  source TEXT NOT NULL DEFAULT 'manual',    -- 'manual' or 'oneproxy'
  quality_score INTEGER,                     -- 0-100 (1proxy only)
  latency_ms INTEGER,                        -- milliseconds (1proxy only)
  anonymity TEXT,                            -- transparent/anonymous/elite
  google_access INTEGER DEFAULT 0,           -- can access Google? (1proxy)
  last_validated TEXT,                       -- ISO timestamp (1proxy)
  country_code TEXT,                         -- ISO 2-letter code (1proxy)
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

Table

CREATE TABLE proxy_assignments (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  proxy_id TEXT NOT NULL REFERENCES proxy_registry(id),
  scope TEXT NOT NULL,        -- 'global', 'provider', 'account', 'combo'
  scope_id TEXT,              -- provider ID, connection ID, or combo ID
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL,
  UNIQUE(scope, scope_id)
);

---

Related documentation:

User Guide — General setup and configuration
• API Reference — Full API documentation
• Environment Config — All environment variables