feat(api): proxyUrl for residential/custom proxy egress on the API block (#5867)

* feat(api): add proxyUrl for residential/custom proxy egress on the API block

The HTTP/API block egresses from the app runtime's fixed datacenter IPs via
secureFetchWithPinnedIP, so targets behind Cloudflare/WAF that block datacenter
IPs (e.g. state .gov license portals) return 403/429 even when the identical
request works from a browser. There was no way to route a request through a
residential/custom proxy.

Add an optional `proxyUrl` field (Advanced) to the API block. When set, the
request routes through the given http:// proxy so it egresses from that proxy's
IP.

Security:
- validateAndPinProxyUrl resolves the proxy host's DNS and blocks
  private/reserved/loopback IPs (same SSRF guard as target URLs), then pins the
  connection by rewriting the host to the resolved IP (creds/port preserved),
  closing the DNS-rebinding window.
- Restricted to the http: proxy scheme (https/socks rejected) so host pinning is
  safe without breaking TLS-to-proxy SNI.
- Target-IP pinning is intentionally bypassed when a proxy is active (the proxy
  resolves the target); target URL validation still runs.

Threaded block field -> http tool param -> formatRequestParams ->
executeToolRequest (validate + pin) -> secureFetchWithPinnedIP, which swaps its
pinned Node agent for HttpsProxyAgent/HttpProxyAgent (keyed off target protocol)
when proxyUrl is set.

* docs(api): document the Proxy URL advanced field and steer proxy credentials to env vars

* fix(api): reject loopback/private proxy hosts unconditionally, closing the self-hosted rebinding gap

* chore(api): tighten proxy-path inline comments

---------

Co-authored-by: Marcus Chandra <mzxchandra@gmail.com>

Author: waleedlatif1

apps/docs/content/docs/en/workflows/blocks/api.mdx

@@ -40,6 +40,7 @@ The request payload for POST, PUT, and PATCH, sent as JSON. Type it directly, or
 - **Retries.** Number of retry attempts on timeouts, `429` responses, and `5xx` errors. Defaults to 0.
 - **Retry delay / Max retry delay (ms).** The exponential-backoff bounds used between retries.
 - **Retry non-idempotent methods.** Off by default, so POST and PATCH are not retried, which avoids duplicate writes. Turn it on only when a repeated request is safe.
+- **Proxy URL.** Optional `http://` proxy the request egresses through, such as a residential proxy for targets that block datacenter IPs. The proxy host must be publicly reachable, and only the `http://` scheme is supported (an `https://` target still tunnels through it securely). Keep proxy credentials in an environment variable and reference it as `{{PROXY_URL}}` rather than typing them into the field.
 
 ## Outputs
 

apps/sim/blocks/blocks/api.ts

@@ -123,6 +123,15 @@ Example:
       description: 'Allow retries for POST/PATCH requests (may create duplicate requests)',
       mode: 'advanced',
     },
+    {
+      id: 'proxyUrl',
+      title: 'Proxy URL',
+      type: 'short-input',
+      placeholder: 'http://user:pass@proxy.host:port or {{PROXY_URL}}',
+      description:
+        'Optional. Route this request through an http:// proxy (e.g. a residential proxy). Must be http://; the proxy host must be publicly reachable. Keep credentials in an environment variable and reference it like {{PROXY_URL}}.',
+      mode: 'advanced',
+    },
   ],
   tools: {
     access: ['http_request'],
@@ -144,6 +153,10 @@ Example:
       type: 'boolean',
       description: 'Allow retries for non-idempotent methods like POST/PATCH',
     },
+    proxyUrl: {
+      type: 'string',
+      description: 'Optional http:// proxy URL to route the request through',
+    },
   },
   outputs: {
     data: { type: 'json', description: 'API response data (JSON, text, or other formats)' },

apps/sim/lib/core/security/input-validation.server.ts

@@ -5,6 +5,8 @@ import type { LookupFunction } from 'net'
 import { createLogger } from '@sim/logger'
 import { toError } from '@sim/utils/errors'
 import { omit } from '@sim/utils/object'
+import { HttpProxyAgent } from 'http-proxy-agent'
+import { HttpsProxyAgent } from 'https-proxy-agent'
 import * as ipaddr from 'ipaddr.js'
 import { Agent, type RequestInit as UndiciRequestInit, fetch as undiciFetch } from 'undici'
 import { isHosted, isPrivateDatabaseHostsAllowed } from '@/lib/core/config/env-flags'
@@ -148,6 +150,71 @@ export async function validateUrlWithDNS(
   }
 }
 
+/**
+ * Result of validating a user-supplied HTTP proxy URL.
+ */
+export interface ProxyValidationResult {
+  isValid: boolean
+  /** Proxy URL with hostname rewritten to the resolved IP (creds/port preserved) to pin the proxy connection. */
+  pinnedProxyUrl?: string
+  error?: string
+}
+
+/**
+ * Validates a user-supplied HTTP proxy URL and returns an IP-pinned form.
+ *
+ * When a request routes through a proxy, the TCP connection targets the proxy
+ * host (the proxy resolves the destination), so target-IP pinning no longer
+ * governs egress and the proxy URL becomes the SSRF surface. This function:
+ * 1. Enforces the `http:` scheme (raw TCP to the proxy, no TLS-to-proxy SNI to
+ *    reconcile, so the host can be safely rewritten to an IP).
+ * 2. Resolves the proxy host's DNS and blocks private/reserved/loopback IPs via
+ *    {@link validateUrlWithDNS}.
+ * 3. Pins the connection by rewriting the hostname to the resolved IP while
+ *    preserving credentials/port, closing the DNS-rebinding (TOCTOU) window.
+ *
+ * @param proxyUrl - The proxy URL (e.g. `http://user:pass@host:port`)
+ */
+export async function validateAndPinProxyUrl(
+  proxyUrl: string | null | undefined
+): Promise<ProxyValidationResult> {
+  if (!proxyUrl || typeof proxyUrl !== 'string') {
+    return { isValid: false, error: 'proxyUrl must be a string' }
+  }
+
+  let parsed: URL
+  try {
+    parsed = new URL(proxyUrl)
+  } catch {
+    return { isValid: false, error: 'proxyUrl must be a valid URL' }
+  }
+
+  if (parsed.protocol !== 'http:') {
+    return {
+      isValid: false,
+      error: 'proxyUrl must use http:// (https/socks proxies are not supported)',
+    }
+  }
+
+  const validation = await validateUrlWithDNS(proxyUrl, 'proxyUrl', { allowHttp: true })
+  if (!validation.isValid) {
+    return { isValid: false, error: validation.error }
+  }
+
+  const resolvedIP = validation.resolvedIP!
+
+  // validateUrlWithDNS permits loopback for self-hosted dev targets; a proxy governs
+  // egress, so loopback/private proxy hosts stay blocked unconditionally.
+  if (isPrivateOrReservedIP(resolvedIP)) {
+    return { isValid: false, error: 'proxyUrl resolves to a blocked IP address' }
+  }
+
+  // Bracket IPv6 literals: assigning an unbracketed IPv6 address to URL.hostname
+  // is a no-op, which would leave the DNS hostname in place and reopen rebinding.
+  parsed.hostname = resolvedIP.includes(':') ? `[${resolvedIP}]` : resolvedIP
+  return { isValid: true, pinnedProxyUrl: parsed.toString() }
+}
+
 /**
  * Validates a database hostname by resolving DNS and checking the resolved IP
  * against private/reserved ranges to prevent SSRF via database connections.
@@ -343,6 +410,12 @@ export interface SecureFetchOptions {
   signal?: AbortSignal
   /** Drop the Authorization header when following a redirect, so it is not sent to the redirect target's origin. */
   stripAuthOnRedirect?: boolean
+  /**
+   * Pre-validated, IP-pinned `http://` proxy URL (see {@link validateAndPinProxyUrl}).
+   * When set, the connection routes through this proxy and target-IP pinning is
+   * bypassed (the proxy resolves the target).
+   */
+  proxyUrl?: string
 }
 
 export class SecureFetchHeaders {
@@ -678,11 +751,17 @@ export async function secureFetchWithPinnedIP(
     const defaultPort = isHttps ? 443 : 80
     const port = parsed.port ? Number.parseInt(parsed.port, 10) : defaultPort
 
-    const lookup = createPinnedLookup(resolvedIP)
-
-    const agentOptions: http.AgentOptions = { lookup }
-
-    const agent = isHttps ? new https.Agent(agentOptions) : new http.Agent(agentOptions)
+    let agent: http.Agent
+    if (options.proxyUrl) {
+      // Proxy connection is already IP-pinned by validateAndPinProxyUrl; target-IP
+      // pinning is intentionally bypassed (the proxy resolves the target). https
+      // targets tunnel via CONNECT, http targets use absolute-URI forwarding.
+      agent = isHttps ? new HttpsProxyAgent(options.proxyUrl) : new HttpProxyAgent(options.proxyUrl)
+    } else {
+      const lookup = createPinnedLookup(resolvedIP)
+      const agentOptions: http.AgentOptions = { lookup }
+      agent = isHttps ? new https.Agent(agentOptions) : new http.Agent(agentOptions)
+    }
 
     const { 'accept-encoding': _, ...sanitizedHeaders } = options.headers ?? {}
 

apps/sim/lib/core/security/input-validation.test.ts

@@ -28,6 +28,7 @@ import {
 } from '@/lib/core/security/input-validation'
 import {
   isPrivateOrReservedIP,
+  validateAndPinProxyUrl,
   validateDatabaseHost,
   validateUrlWithDNS,
 } from '@/lib/core/security/input-validation.server'
@@ -843,6 +844,73 @@ describe('validateDatabaseHost', () => {
   })
 })
 
+describe('validateAndPinProxyUrl', () => {
+  it('should reject a null/empty proxy URL', async () => {
+    expect((await validateAndPinProxyUrl(null)).isValid).toBe(false)
+    expect((await validateAndPinProxyUrl('')).isValid).toBe(false)
+  })
+
+  it('should reject a malformed URL', async () => {
+    const result = await validateAndPinProxyUrl('not a url')
+    expect(result.isValid).toBe(false)
+    expect(result.error).toContain('valid URL')
+  })
+
+  it('should reject an https:// proxy scheme', async () => {
+    const result = await validateAndPinProxyUrl('https://proxy.example.com:8080')
+    expect(result.isValid).toBe(false)
+    expect(result.error).toContain('http://')
+  })
+
+  it('should reject a socks5:// proxy scheme', async () => {
+    const result = await validateAndPinProxyUrl('socks5://proxy.example.com:1080')
+    expect(result.isValid).toBe(false)
+    expect(result.error).toContain('http://')
+  })
+
+  it('should reject a proxy host that is a private IP', async () => {
+    const result = await validateAndPinProxyUrl('http://user:pass@192.168.1.1:8080')
+    expect(result.isValid).toBe(false)
+    expect(result.error).toMatch(/private IP|blocked IP/)
+  })
+
+  it('should reject a loopback proxy host even off the hosted platform', async () => {
+    const localhost = await validateAndPinProxyUrl('http://localhost:3128')
+    expect(localhost.isValid).toBe(false)
+    expect(localhost.error).toContain('blocked IP')
+    const loopback = await validateAndPinProxyUrl('http://127.0.0.1:3128')
+    expect(loopback.isValid).toBe(false)
+    expect(loopback.error).toContain('blocked IP')
+  })
+
+  it('should reject a proxy host that is the metadata IP', async () => {
+    const result = await validateAndPinProxyUrl('http://169.254.169.254:80')
+    expect(result.isValid).toBe(false)
+    expect(result.error).toMatch(/private IP|blocked IP/)
+  })
+
+  it('should accept a public proxy host and pin the hostname to the resolved IP, preserving creds/port', async () => {
+    const result = await validateAndPinProxyUrl('http://user:pass@8.8.8.8:8080')
+    expect(result.isValid).toBe(true)
+    const pinned = new URL(result.pinnedProxyUrl!)
+    expect(pinned.protocol).toBe('http:')
+    expect(pinned.hostname).toBe('8.8.8.8')
+    expect(pinned.username).toBe('user')
+    expect(pinned.password).toBe('pass')
+    expect(pinned.port).toBe('8080')
+  })
+
+  it('should bracket an IPv6 resolved address so the pinned host is the IP, not the original name', async () => {
+    const result = await validateAndPinProxyUrl('http://user:pass@[2606:4700:4700::1111]:8080')
+    expect(result.isValid).toBe(true)
+    const pinned = new URL(result.pinnedProxyUrl!)
+    expect(pinned.hostname).toBe('[2606:4700:4700::1111]')
+    expect(pinned.username).toBe('user')
+    expect(pinned.password).toBe('pass')
+    expect(pinned.port).toBe('8080')
+  })
+})
+
 describe('validateInteger', () => {
   describe('valid integers', () => {
     it.concurrent('should accept positive integers', () => {

apps/sim/package.json

@@ -155,6 +155,8 @@
     "gray-matter": "^4.0.3",
     "groq-sdk": "^0.15.0",
     "html-to-text": "^9.0.5",
+    "http-proxy-agent": "7.0.2",
+    "https-proxy-agent": "7.0.6",
     "idb-keyval": "6.2.2",
     "image-size": "1.2.1",
     "imapflow": "1.2.4",

apps/sim/tools/http/request.ts

@@ -51,6 +51,11 @@ export const requestTool: ToolConfig<RequestParams, RequestResponse> = {
       visibility: 'user-or-llm',
       description: 'Form data to send (will set appropriate Content-Type)',
     },
+    proxyUrl: {
+      type: 'string',
+      visibility: 'user-only',
+      description: 'Route the request through an http:// proxy (e.g. http://user:pass@host:port).',
+    },
     timeout: {
       type: 'number',
       visibility: 'user-only',

apps/sim/tools/http/types.ts

@@ -8,6 +8,7 @@ export interface RequestParams {
   params?: TableRow[] | string
   pathParams?: Record<string, string>
   formData?: Record<string, string | Blob>
+  proxyUrl?: string
   timeout?: number
   retries?: number
   retryDelayMs?: number

apps/sim/tools/index.test.ts

@@ -958,6 +958,77 @@ describe('Automatic Internal Route Detection', () => {
     Object.assign(tools, originalTools)
   })
 
+  it('should validate + pin a proxyUrl param and pass it to secureFetchWithPinnedIP', async () => {
+    inputValidationMockFns.mockValidateAndPinProxyUrl.mockResolvedValue({
+      isValid: true,
+      pinnedProxyUrl: 'http://user:pass@1.2.3.4:8080/',
+    })
+
+    const mockTool = {
+      id: 'test_external_proxy',
+      name: 'Test External Proxy Tool',
+      description: 'A test tool that routes through a proxy',
+      version: '1.0.0',
+      params: {},
+      request: {
+        url: 'https://api.example.com/endpoint',
+        method: 'GET',
+        headers: () => ({ 'Content-Type': 'application/json' }),
+      },
+      transformResponse: vi.fn().mockResolvedValue({ success: true, output: {} }),
+    }
+
+    const originalTools = { ...tools }
+    ;(tools as any).test_external_proxy = mockTool
+
+    await executeTool('test_external_proxy', { proxyUrl: 'http://user:pass@proxy.host:8080' })
+
+    expect(inputValidationMockFns.mockValidateAndPinProxyUrl).toHaveBeenCalledWith(
+      'http://user:pass@proxy.host:8080'
+    )
+    expect(mockSecureFetchWithPinnedIP).toHaveBeenCalledWith(
+      'https://api.example.com/endpoint',
+      '93.184.216.34',
+      expect.objectContaining({ proxyUrl: 'http://user:pass@1.2.3.4:8080/' })
+    )
+
+    Object.assign(tools, originalTools)
+  })
+
+  it('should throw when the proxyUrl param fails validation', async () => {
+    inputValidationMockFns.mockValidateAndPinProxyUrl.mockResolvedValue({
+      isValid: false,
+      error: 'proxyUrl must use http:// (https/socks proxies are not supported)',
+    })
+
+    const mockTool = {
+      id: 'test_external_bad_proxy',
+      name: 'Test External Bad Proxy Tool',
+      description: 'A test tool with an invalid proxy',
+      version: '1.0.0',
+      params: {},
+      request: {
+        url: 'https://api.example.com/endpoint',
+        method: 'GET',
+        headers: () => ({ 'Content-Type': 'application/json' }),
+      },
+      transformResponse: vi.fn().mockResolvedValue({ success: true, output: {} }),
+    }
+
+    const originalTools = { ...tools }
+    ;(tools as any).test_external_bad_proxy = mockTool
+
+    const result = await executeTool('test_external_bad_proxy', {
+      proxyUrl: 'https://proxy.host:8080',
+    })
+
+    expect(result.success).toBe(false)
+    expect(result.error).toContain('Invalid proxy URL')
+    expect(mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
+
+    Object.assign(tools, originalTools)
+  })
+
   it('should handle dynamic URLs that resolve to internal routes', async () => {
     const mockTool = {
       id: 'test_dynamic_internal',

apps/sim/tools/index.ts

@@ -14,6 +14,7 @@ import { DEFAULT_EXECUTION_TIMEOUT_MS, getMaxExecutionTimeout } from '@/lib/core
 import { getHostedKeyRateLimiter } from '@/lib/core/rate-limiter'
 import {
   secureFetchWithPinnedIP,
+  validateAndPinProxyUrl,
   validateUrlWithDNS,
 } from '@/lib/core/security/input-validation.server'
 import { PlatformEvents } from '@/lib/core/telemetry'
@@ -1809,13 +1810,23 @@ async function executeToolRequest(
             throw new Error(`Invalid tool URL: ${urlValidation.error}`)
           }
 
+          let proxyOption: string | undefined
+          if (requestParams.proxyUrl) {
+            const proxyValidation = await validateAndPinProxyUrl(requestParams.proxyUrl)
+            if (!proxyValidation.isValid) {
+              throw new Error(`Invalid proxy URL: ${proxyValidation.error}`)
+            }
+            proxyOption = proxyValidation.pinnedProxyUrl
+          }
+
           const secureResponse = await secureFetchWithPinnedIP(fullUrl, urlValidation.resolvedIP!, {
             method: requestParams.method,
             headers: headersRecord,
             body: requestParams.body ?? undefined,
             timeout: requestParams.timeout,
             maxResponseBytes: MAX_TOOL_RESPONSE_BODY_BYTES,
             signal,
+            proxyUrl: proxyOption,
           })
 
           const responseHeaders = new Headers(secureResponse.headers.toRecord())

apps/sim/tools/utils.test.ts

@@ -209,6 +209,17 @@ describe('formatRequestParams', () => {
 
     expect(result.body).toBe('{"prompt": "Hello"}\n{"prompt": "World"}')
   })
+
+  it.concurrent('should pass through a non-empty proxyUrl (trimmed)', () => {
+    const result = formatRequestParams(mockTool, { proxyUrl: '  http://user:pass@host:8080  ' })
+    expect(result.proxyUrl).toBe('http://user:pass@host:8080')
+  })
+
+  it.concurrent('should omit proxyUrl when blank, whitespace, or absent', () => {
+    expect(formatRequestParams(mockTool, {}).proxyUrl).toBeUndefined()
+    expect(formatRequestParams(mockTool, { proxyUrl: '' }).proxyUrl).toBeUndefined()
+    expect(formatRequestParams(mockTool, { proxyUrl: '   ' }).proxyUrl).toBeUndefined()
+  })
 })
 
 describe('validateRequiredParametersAfterMerge', () => {