Product documentation
Citrix SecurSpaces™
View PDF

Configure AI Gateway routing in SecurSpaces

August 13, 2026
Contributed by: 
T

You can route selected AI service traffic from Citrix SecurSpaces™ workspaces through an internal AI Gateway by configuring Helm values. Use this option when your organization wants centralized routing or policy control for AI provider endpoints.

Routing AI traffic through a gateway also gives you a single place to measure AI usage. SecurSpaces tags each forwarded request with the user, project, and workspace it came from, so the gateway can report which teams and developers are consuming tokens. See Report on AI usage.

What SecurSpaces does, and what the gateway does

The two halves are worth separating, because the split decides which questions this page answers.

SecurSpaces provides the interception and the attribution. The SecurSpaces proxy service already terminates and inspects workspace traffic. It recognizes requests bound for a configured AI endpoint and tags each one with the user, project, and workspace that produced it. That is a platform capability and it does not depend on which gateway you run.

The gateway provides routing and policy. Where a request goes, which credential is used, rate limits, and the reporting surface are the gateway’s job.

Which gateway

SecurSpaces forwards to whatever service address you configure in platform.aiGateway.address, so the gateway is your choice:

Gateway Notes
Envoy AI Gateway What this page covers, including installation
NetScaler AI Gateway An alternative if you already run NetScaler. See AI gateway in the NetScaler documentation

A note on terminology

The industry has not settled on one name for this component. AI Bridge is used by some vendors for the same concept. Across Citrix products it is called an AI Gateway, and that is the term used throughout this documentation.

Model Context Protocol governance

Governing MCP traffic — which tools an agent may reach and what it may do through them — is outside what SecurSpaces provides. SecurSpaces governs the workspace an agent runs in and attributes what it consumes; it does not inspect or police MCP calls.

Where MCP governance is required, NetScaler provides it. See MCP gateway in the NetScaler documentation.

How AI traffic is routed

AI traffic flows from the workspace to the SecurSpaces proxy service, then to the AI Gateway, and finally to the LLM endpoint.

The SecurSpaces proxy service already terminates, inspects, and re-encrypts HTTPS traffic. AI Gateway routing reuses that capability to identify requests that are destined for a configured LLM endpoint, add SecurSpaces metadata to them, and forward them to the gateway. Traffic that does not match a configured endpoint is unaffected.

For running agents inside workspaces — isolation, credential scope, and cost — see Run AI coding agents in workspaces.

Prerequisites

  • An internal AI Gateway service that is reachable from the SecurSpaces proxy service pods. If you do not have one, see Install Envoy AI Gateway.
  • The DNS endpoint names that must be routed through the AI Gateway
  • Access to update the SecurSpaces Helm values and run helm upgrade

Install Envoy AI Gateway

SecurSpaces works with any gateway that accepts the forwarded traffic. Envoy AI Gateway is the reference deployment, and this section covers what is specific to using it with SecurSpaces. For the installation itself, follow the Envoy AI Gateway documentation, which stays current with the project.

The installation has two parts, both by Helm chart:

Component Namespace
Envoy Gateway, the control and data plane it builds on envoy-gateway-system
Envoy AI Gateway, its CRDs and controller envoy-ai-gateway-system

Note:

Installing Envoy Gateway does not interfere with your existing ingress controller. It creates its own proxy pods and services in its own namespace, and leaves NGINX, NetScaler, HAProxy, or anything else serving the platform untouched. See Ingress.

Envoy AI Gateway requires Kubernetes 1.32 or later, which any cluster running SecurSpaces already exceeds. See System requirements.

Pin the chart versions rather than tracking the latest tag. The container tags for in-development versions are overwritten, so an unpinned install can change under you between deployments.

When the gateway is running, set platform.aiGateway.address to its internal service address, as described in Configure platform-wide AI Gateway routing.

Increase the client buffer limit

AI requests and responses are considerably larger than typical web traffic, and the Envoy default buffer is not sized for them. Without this, large prompts and long completions are truncated:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: ClientTrafficPolicy
metadata:
  name: client-buffer-limit
spec:
  targetRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: <your-gateway-name>
  connection:
    bufferLimit: 50Mi
<!--NeedCopy-->

Set explicit CPU and memory on the Envoy proxy deployment as well. The reference configuration leaves them empty, which is workable in a lab and not in production.

Rate limiting

Envoy AI Gateway can apply token-based rate limits per model, backed by Redis. This is configured entirely on the gateway and needs nothing from SecurSpaces. See the Envoy AI Gateway documentation for the BackendTrafficPolicy and token-tracking configuration.

Configure platform-wide AI Gateway routing

Add the platform.aiGateway block to your Helm values:

platform:
  aiGateway:
    address: "http://envoy-default-envoy-ai-gateway-07856df5.envoy-gateway-system.svc.cluster.local"
    headers:
      userIdHeader: "x-user-id"
      projectIdHeader: "x-project-id"
      workspaceIdHeader: "x-workspace-id"
      hideProjectName: false
    healthCheck:
      enabled: false
      port: "80"
      failOpen: false
    dnsEndpoints:
      - "api.business.githubcopilot.com."
      - "copilot-proxy.githubusercontent.com."
      - "api.openai.com."
      - "chat.openai.com."
      - "chatgpt.com."
      - "api.anthropic.com."
      - "claude.ai."
      - "generativelanguage.googleapis.com."
      - "gemini.google.com."
      - "bard.google.com."
<!--NeedCopy-->

The address value is the internal service address for the AI Gateway, and can include a scheme. The dnsEndpoints list defines the AI provider domains that SecurSpaces intercepts and routes through that gateway. Each entry is a fully qualified domain name with a trailing dot, and wildcard entries such as "*.openai.azure.com." are supported.

SecurSpaces ships a default endpoint list that covers the most common public LLM providers, including GitHub Copilot, OpenAI, Anthropic, Google, Azure OpenAI, Amazon Bedrock, Mistral, and Hugging Face. The list is refreshed as part of the normal release cycle. Between releases, keep the list current yourself, and add any private or self-hosted LLM endpoints your organization uses.

Identify AI usage by user, project, and workspace

SecurSpaces adds metadata to every request it forwards to the AI Gateway, so that AI usage can be attributed to the workspace that produced it. The gateway and your monitoring stack use these headers to break down usage by user, project, and workspace.

Configure the header names under platform.aiGateway.headers:

Value Default Description
userIdHeader x-user-id Header carrying the ID of the user who made the request.
projectIdHeader x-project-id Header carrying the project the workspace belongs to.
workspaceIdHeader x-workspace-id Header carrying the ID of the originating workspace.
hideProjectName false When false, the project header carries the project name. Set to true to send the numeric project ID instead.

Leave a header name empty to stop SecurSpaces from sending that value.

Note

Keep hideProjectName set to false if you want reports to show readable project names. Set it to true when project names are themselves sensitive and must not leave the cluster.

Route GitHub Copilot traffic

GitHub Copilot needs extra handling, because Envoy AI Gateway does not recognize it as a provider on its own. SecurSpaces bridges that gap for api.githubcopilot.com and api.business.githubcopilot.com: it presents each request in a form the gateway’s processors recognize, and adds headers your route rules can select on.

This covers OpenAI-compatible chat completions, the OpenAI responses API, and Anthropic models such as Claude. You configure the routes; the rest is automatic.

Headers to match in your routes

Route rules on the gateway select a backend using the headers SecurSpaces adds:

Header Value Match it to
x-ai-process true Select AI traffic that the gateway should process
x-original-host The host the workspace requested Choose the right Copilot backend
x-ai-provider anthropic Route Anthropic requests, when your teams use Claude through Copilot

Configure the gateway

Define a Backend for each Copilot host, a BackendTLSPolicy so the gateway originates TLS to it, and route rules that match on the headers above. For example:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: github-copilot-chat
spec:
  endpoints:
    - fqdn:
        hostname: api.business.githubcopilot.com
        port: 443
---
apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
  name: github-copilot-chat-tls
spec:
  targetRefs:
    - group: gateway.envoyproxy.io
      kind: Backend
      name: github-copilot-chat
  validation:
    hostname: api.business.githubcopilot.com
    wellKnownCACertificates: System
<!--NeedCopy-->

Then match the headers in your route, and allow a generous request timeout because model responses are slow:

rules:
  - timeouts:
      request: 300s
    matches:
      - headers:
          - type: Exact
            name: x-ai-process
            value: "true"
          - type: Exact
            name: x-original-host
            value: api.business.githubcopilot.com
    backendRefs:
      - name: github-copilot-chat
<!--NeedCopy-->

Repeat for the other Copilot hosts your developers reach.

Claude through Copilot

If your teams use Claude, add an AIServiceBackend with the Anthropic schema and route x-ai-provider: anthropic to it.

Set prefix: "/v1" on the schema. SecurSpaces presents Anthropic requests as /anthropic/v1/messages so that the gateway selects its Anthropic processor. The prefix is what restores the real upstream path afterwards. Without it the request reaches Anthropic with the routing prefix still attached, and fails.

apiVersion: aigateway.envoyproxy.io/v1beta1
kind: AIServiceBackend
metadata:
  name: github-copilot-chat-anthropic
spec:
  schema:
    name: Anthropic
    prefix: "/v1"
  backendRef:
    name: github-copilot-chat
    kind: Backend
    group: gateway.envoyproxy.io
<!--NeedCopy-->

Note:

Copilot’s MCP endpoint can also be published through the gateway with an MCPRoute, forwarding the caller’s Authorization header so each developer authenticates as themselves.

Tool types on the responses API

The gateway’s external processor rejects a /v1/responses request that carries a tool type it cannot parse, with 400 unknown tool type. To keep those requests working, SecurSpaces removes unrecognized tool types before forwarding.

The list is held by SecurSpaces, not by your gateway, so it changes with a SecurSpaces release rather than when you upgrade Envoy AI Gateway. It currently allows function, file_search, computer_use_preview, web_search, web_search_2025_08_26, mcp, code_interpreter, image_generation, custom, local_shell, shell, web_search_preview, web_search_preview_2025_03_11, and apply_patch.

Important:

A tool outside this set is dropped silently. The request succeeds and its token usage is still reported, but that tool never reaches the provider. These are generally client-side tools that the upstream API does not act on, so the effect is usually invisible — but if a developer reports that a tool works outside SecurSpaces and not inside it, this is the first thing to check.

Configure AI Gateway health checking

By default, SecurSpaces does not health check the AI Gateway. Turn on health checking to control what happens to AI traffic when the gateway is unavailable.

Configure health checking under platform.aiGateway.healthCheck:

Value Default Description
enabled false When true, SecurSpaces runs periodic TCP health checks against the AI Gateway.
port 80 The port SecurSpaces dials for the health check.
failOpen false Controls the behavior when the gateway is unhealthy.

When the gateway is unhealthy:

  • With failOpen: true, AI traffic bypasses the gateway and goes directly to the AI provider. Developers are not interrupted, but no usage data is recorded while the gateway is down.
  • With failOpen: false, the request returns an error to the user. Use this setting when AI traffic must never bypass the gateway.

Warning

failOpen defaults to false. If you enable health checking without setting failOpen, an AI Gateway outage stops developers from reaching AI providers. Set failOpen: true if you would rather lose usage data than block AI requests.

Override AI Gateway routing for a region

For an external region, add region.aiGateway to override the platform-wide settings:

region:
  isExternalRegion: true
  aiGateway:
    address: "ai-gateway.region.example.svc.cluster.local"
    headers:
      userIdHeader: "x-user-id"
      projectIdHeader: "x-project-id"
      workspaceIdHeader: "x-workspace-id"
    healthCheck:
      enabled: false
      port: "80"
      failOpen: false
    dnsEndpoints:
      - "api.openai.com."
      - "api.anthropic.com."
<!--NeedCopy-->

The regional values apply only to that region. If you omit region.aiGateway, the region uses the platform-wide platform.aiGateway configuration.

Apply the configuration

  1. Update your SecurSpaces Helm values file.
  2. Run your standard helm upgrade command.
  3. Restart any affected workspace sessions if you need existing connections to use the new routing.

After the upgrade, SecurSpaces routes requests for the configured DNS endpoints through the configured AI Gateway address.

Report on AI usage

Routing AI traffic through a gateway lets you answer questions such as which models are in use, how many tokens each project consumes, and which users generate the most requests. This information supports cost attribution and chargeback discussions.

SecurSpaces does not parse AI traffic or store usage metrics itself. The AI Gateway extracts request counts, model names, and token counts, and exports them to your monitoring system. The accuracy and provider coverage of the resulting reports depend on the parsing support of the gateway you deploy.

Reference deployment

The following stack is validated for use with SecurSpaces:

  • Envoy AI Gateway — receives AI traffic from the SecurSpaces proxy service, forwards it to the LLM provider, and exposes metrics such as request counts, model names, and input and output token counts.
  • Prometheus — scrapes and stores the metrics that Envoy AI Gateway exposes.
  • Grafana — queries Prometheus and presents the dashboards.

Deploy all three in the same Kubernetes cluster as SecurSpaces, then set platform.aiGateway.address to the internal service address of Envoy AI Gateway.

This is a reference path, not a requirement. Envoy AI Gateway supports OpenTelemetry and a broad range of monitoring integrations, so you can send the same data to your existing monitoring infrastructure instead.

Sample Grafana dashboard

SecurSpaces provides a sample Grafana dashboard that you can import and adapt. The dashboard reads the SecurSpaces metadata headers, so usage can be filtered and grouped by model, project, and user.

The dashboard includes:

  • Summary totals — total input tokens, total output tokens, combined token count, and total LLM request count.
  • Token usage rate — tokens per minute, broken down into input, output, cached input, cache creation, and reasoning tokens.
  • Request rate and response time — requests per second, and LLM response time at the 50th, 95th, and 99th percentiles.
  • Average tokens per request — average input and output tokens per request.
  • Rate limiting — rate limited requests, requests over the global rate limit, and users over their rate limit.
  • Upstream response time — response time of the LLM provider at the 50th and 95th percentiles.
  • By Project ID — token usage, request rate, and total tokens per project.
  • By User ID — token usage per user over time.
  • By Model — token usage, request rate, and total tokens per model.

Use the Model, Project ID, and User ID selectors at the top of the dashboard to filter every panel.

Note

Panels that break usage down by project and user rely on the metadata headers described in Identify AI usage by user, project, and workspace. If those headers are not configured, the corresponding panels are empty.

Configure AI Gateway routing in SecurSpaces
August 13, 2026
Contributed by: 
T
August 13, 2026
Contributed by: 
T

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.