Custom hosts

Route requests to privately hosted or local models using custom host URLs, and understand Portkey’s host validation and security rules.

Custom hosts with private network routing — including the TRUSTED_CUSTOM_HOSTS allowlist — applies only to hybrid and air-gapped enterprise deployments of the Portkey AI Gateway. On Portkey SaaS, custom host URLs must be publicly reachable; routing to private or internal network IPs is not supported.

The custom_host parameter routes Portkey Gateway requests to your own model endpoints — whether running locally, in a private cloud, or on custom infrastructure. Portkey validates all custom host URLs to prevent SSRF attacks.

Setting a custom host

Specify a custom host using one of these methods:

Method	Parameter
HTTP header	x-portkey-custom-host
Python SDK	custom_host
Node.js SDK	customHost
Gateway config	custom_host (in the target object)

Python

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="openai",
    custom_host="https://your-llm-server.com/v1/"
)

response = portkey.chat.completions.create(
    model="your-model",
    messages=[{"role": "user", "content": "Hello"}]
)

import Portkey from 'portkey-ai'

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "openai",
    customHost: "https://your-llm-server.com/v1/"
})

const response = await portkey.chat.completions.create({
    model: "your-model",
    messages: [{ role: "user", content: "Hello" }]
})

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: openai" \
  -H "x-portkey-custom-host: https://your-llm-server.com/v1/" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Also set custom_host in a Gateway config target:

{
  "strategy": { "mode": "fallback" },
  "targets": [
    {
      "provider": "openai",
      "custom_host": "https://your-private-llm.com/v1",
      "forward_headers": ["Authorization"]
    },
    {
      "provider": "openai",
      "api_key": "sk-xxxxx"
    }
  ]
}

Include the version path (e.g., /v1) in the custom_host URL. Portkey appends the endpoint path (/chat/completions, /responses, etc.) automatically.

For a full guide on integrating private LLMs, see Bring Your Own LLM.

---

Blocked host patterns

Portkey validates all custom host URLs to prevent requests to internal network resources. The following IP ranges and patterns are blocked by default:

Private IPv4 ranges

Range	Description
10.0.0.0/8	Private network (Class A)
172.16.0.0/12	Private network (Class B)
192.168.0.0/16	Private network (Class C)

Reserved IPv4 ranges

Range	Description
127.0.0.0/8	Loopback addresses
169.254.0.0/16	Link-local addresses
100.64.0.0/10	Carrier-grade NAT (CGNAT)
0.0.0.0/8	Non-routable (includes 0.0.0.0)
224.0.0.0/4	Multicast, reserved, and broadcast

Cloud metadata endpoints

Address	Description
169.254.169.254	Cloud provider metadata service (AWS, GCP, Azure)

IPv6 local and private ranges

Range	Description
::1	IPv6 loopback
::	IPv6 unspecified
fc00::/7	Unique local addresses (fc* / fd*)
fe80::/10	Link-local addresses
fec0::/10	Site-local addresses (deprecated)
fd00:ec2::*	AWS IMDSv2 IPv6 endpoint

IP obfuscation tricks

The following alternate IP representations are also blocked to prevent bypass attempts:

• Decimal form — e.g., 2130706433 (resolves to 127.0.0.1)
• Hexadecimal form — e.g., 0x7f000001 (resolves to 127.0.0.1)
• Shortened IPv4 — e.g., 127.1 (resolves to 127.0.0.1)
• Octal notation — e.g., 0177.0.0.1 (resolves to 127.0.0.1)

---

Trusted custom hosts (allowlist)

Portkey maintains a trusted hosts allowlist that overrides the blocked patterns above. By default, the following hosts are trusted:

Host	Description
localhost	Local development
127.0.0.1	IPv4 loopback
::1	IPv6 loopback
host.docker.internal	Docker host access

Even though 127.0.0.1 and ::1 fall within blocked ranges, they are allowed through the trusted hosts path. Port validation still applies (must be between 1 and 65535).

Adding hosts to the allowlist

To route to a private network IP (e.g., 172.31.2.45), add it to the trusted hosts allowlist using the TRUSTED_CUSTOM_HOSTS environment variable.

TRUSTED_CUSTOM_HOSTS is available only on self-hosted hybrid and air-gapped enterprise deployments of the Portkey AI Gateway.

Set the environment variable as a comma-separated list of hosts:

TRUSTED_CUSTOM_HOSTS="localhost,127.0.0.1,::1,host.docker.internal,172.31.2.45"

Requests with custom_host set to http://172.31.2.45:8008/v1/ will then pass validation.

When overriding TRUSTED_CUSTOM_HOSTS, include the default values (localhost, 127.0.0.1, ::1, host.docker.internal) along with your additions to preserve the default behavior.

Validation rules for trusted hosts

Even for trusted hosts, Portkey enforces:

• Port range — The port must be between 1 and 65535
• Host-only matching — Only the hostname or IP is checked against the allowlist, not the full URL

---

Common scenarios

Scenario	Default behavior	Action needed
Local development (e.g., Ollama on localhost)	Allowed — localhost and 127.0.0.1 are trusted by default	None. See the Ollama integration guide.
Docker containers (host.docker.internal)	Allowed — trusted by default	None
Private network IP (e.g., 172.31.2.45:8008)	Blocked — falls within 172.16.0.0/12	Add the IP to TRUSTED_CUSTOM_HOSTS (hybrid/air-gapped only)
Cloud metadata (169.254.169.254)	Blocked	Cannot be allowlisted for security reasons