How to Configure Upstream Proxy Settings with SOCKS5 and HTTP Forwarding in OmniRoute

OmniRoute routes every outbound request through configurable upstream proxies—either SOCKS5 or HTTP forward proxies—using environment variables, CLI commands, or REST API calls that persist configurations to the SQLite registry in src/lib/db/proxy.ts.

OmniRoute is an open-source AI request routing layer that requires flexible egress control for corporate networks and privacy-conscious deployments. Understanding how to configure upstream proxy settings with SOCKS5 and HTTP forwarding in OmniRoute ensures all provider requests traverse your preferred proxy infrastructure, whether you need TCP-level tunneling or standard HTTP CONNECT forwarding.

Configuration Surfaces

OmniRoute exposes three interchangeable interfaces for proxy management. Each method ultimately writes to the same underlying datastore and becomes active immediately without requiring a server restart.

Environment Variables

Set process-wide defaults before starting the OmniRoute server. The bootstrap logic in src/proxy.ts reads these variables during startup and registers them as default proxies for all providers lacking explicit overrides.

# SOCKS5 proxy with authentication

export UPSTREAM_PROXY_SOCKS="socks5://user:pwd@proxy.example.com:1080"

# HTTP forward proxy

export UPSTREAM_PROXY_HTTP="http://proxy.example.com:3128"

CLI Commands

Use the omniroute proxy add command implemented in bin/cli/commands/oneproxy.mjs to persist proxies to the database via the internal API. This approach is ideal for automation scripts and CI/CD pipelines.

# Add a SOCKS5 proxy

omniroute proxy add \
  --type socks5 \
  --url socks5://user:pwd@proxy.example.com:1080 \
  --label "Corporate SOCKS5"

# Add an HTTP forwarding proxy

omniroute proxy add \
  --type http \
  --url http://proxy.example.com:3128 \
  --label "Edge HTTP Proxy"

REST API and UI

Send a POST request to /api/v1/proxy with a JSON body validated against the Zod schema in src/shared/validation/schemas/proxy.ts. The web interface at Settings → Proxy uses this same endpoint.

POST /api/v1/proxy HTTP/1.1
Content-Type: application/json

{
  "type": "socks5",
  "url": "socks5://user:pwd@proxy.example.com:1080",
  "label": "Corporate SOCKS5",
  "enabled": true
}

Proxy Routing Architecture

Understanding the request flow helps debug connectivity issues and optimize performance for high-throughput AI workloads.

Registration and Storage

When you add a proxy via any surface, OmniRoute inserts a row into the proxy table managed by src/lib/db/proxy.ts. The schema stores:

• id: Unique identifier
• type: Either socks5 or http
• url: Full proxy URL including credentials
• username/password: Optional authentication fields
• enabled: Boolean activation flag
• createdAt: Timestamp

Selection and Dispatch

The open-sse/utils/proxyDispatcher.ts module evaluates enabled proxies for each outgoing request. It calls open-sse/utils/proxyFamilyResolve.ts to determine the proxy family (SOCKS vs. HTTP) based on the target URL, then attaches the appropriate agent to the fetch call.

Execution and Forwarding Logic

open-sse/utils/proxyFetch.ts constructs the final request using node-fetch or undici:

• SOCKS5 proxies: Uses the socks-proxy-agent library to establish a TCP-level tunnel, supporting both HTTP and HTTPS endpoints transparently.
• HTTP proxies: Uses http-proxy-agent to send the full request URL as-is, relying on the proxy's CONNECT method for forwarding.

Implementation Examples

Configuring Global Defaults via Environment Variables

For Docker containers or systemd services, environment variables provide the cleanest configuration method. Define UPSTREAM_PROXY_SOCKS for TCP tunneling or UPSTREAM_PROXY_HTTP for standard forward proxies before executing the OmniRoute binary.

export UPSTREAM_PROXY_SOCKS="socks5://user:pwd@proxy.example.com:1080"
export UPSTREAM_PROXY_HTTP="http://proxy.example.com:3128"
npm start

Managing Proxies via CLI

The CLI tool validates inputs against the Zod schema and handles database migrations automatically. Each addition returns the generated proxy ID for reference in provider configurations.

# List existing proxies

omniroute proxy list

# Remove a proxy by ID

omniroute proxy remove --id proxy-1234

Programmatic Configuration via REST API

For dynamic environments where proxy endpoints change frequently, automate configuration through the REST API. The endpoint accepts the same payload structure used by the React-based frontend.

curl -X POST http://localhost:3000/api/v1/proxy \
  -H "Content-Type: application/json" \
  -d '{
    "type": "http",
    "url": "http://proxy.example.com:3128",
    "label": "Dynamic HTTP Proxy",
    "enabled": true
  }'

Per-Provider Proxy Overrides

Override global defaults for specific AI providers by editing src/shared/constants/providers.ts and adding a proxyId field referencing the desired registry entry. The resolver in open-sse/services/combo.ts selects this specific proxy for that provider only.

{
  "id": "openai",
  "model": "gpt-4o",
  "proxyId": "proxy-1234"
}

Runtime Verification

Debug active proxy assignments using the dispatcher utility. This function queries the registry and returns the resolved proxy configuration for any registered provider.

import { getActiveProxyForProvider } from '@omniroute/open-sse/utils/proxyDispatcher';

const proxy = await getActiveProxyForProvider('openai');
console.log('Current proxy:', proxy?.url ?? 'Direct connection');

Summary

• Three configuration methods: Environment variables for defaults, CLI for scripting, and REST API for dynamic management.
• Storage layer: All proxies persist to the SQLite proxy table in src/lib/db/proxy.ts with fields for type, URL, credentials, and activation state.
• Agent selection: open-sse/utils/proxyDispatcher.ts chooses between socks-proxy-agent and http-proxy-agent based on the configured type.
• Provider overrides: Individual providers can specify dedicated proxies via the proxyId field in the provider catalog.
• Validation: All inputs pass through the Zod schema defined in src/shared/validation/schemas/proxy.ts.

Frequently Asked Questions

What proxy types does OmniRoute support?

OmniRoute supports SOCKS5 proxies for TCP-level tunneling and standard HTTP forward proxies for CONNECT-based forwarding. The system uses distinct Node.js agent libraries—socks-proxy-agent for SOCKS5 and http-proxy-agent for HTTP—automatically selected by the dispatcher based on the type field stored in src/lib/db/proxy.ts.

How do I set a different proxy for a specific AI provider?

Edit the provider definition in src/shared/constants/providers.ts and add a proxyId property referencing the UUID of your configured proxy from the registry. When the request dispatcher in open-sse/services/combo.ts processes requests for that provider, it prioritizes this specific proxy over global defaults.

Where are proxy configurations stored in OmniRoute?

All proxy configurations persist to a SQLite database table named proxy, managed by the database layer in src/lib/db/proxy.ts. This table stores the proxy URL, authentication credentials, type classification, and enabled status, making configurations durable across server restarts.

Can I use authentication with SOCKS5 proxies?

Yes. Include credentials directly in the URL when configuring via environment variables (socks5://user:password@host:port), CLI (--url socks5://user:password@host:port), or REST API ("url": "socks5://user:password@host:port"). The socks-proxy-agent library parses these credentials and handles authentication handshake automatically during connection establishment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}