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

> Configure upstream proxy settings with SOCKS5 and HTTP forwarding in OmniRoute. Route all outbound requests via environment variables CLI commands or REST API calls. Learn more now

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/proxy.ts)** reads these variables during startup and registers them as default proxies for all providers lacking explicit overrides.

```bash

# 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.

```bash

# 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/schemas/proxy.ts)**. The web interface at *Settings → Proxy* uses this same endpoint.

```http
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/utils/proxyDispatcher.ts)** module evaluates enabled proxies for each outgoing request. It calls **[`open-sse/utils/proxyFamilyResolve.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.

```bash
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.

```bash

# 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.

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers.ts)** and adding a `proxyId` field referencing the desired registry entry. The resolver in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) selects this specific proxy for that provider only.

```json
{
  "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.

```javascript
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/proxy.ts) with fields for type, URL, credentials, and activation state.
- **Agent selection**: [`open-sse/utils/proxyDispatcher.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.