feat(aigw): generate config from OpenAI environment variables (envoyproxy#1233)

**Description**

This implements automatic configuration generation for `aigw run` when
there is no config file and at least the `OPENAI_API_KEY` environment
variables is set.

This makes it easier to get started with OpenAI-compatible backends
without writing or copy/pasting YAML configuration.

Configuration:

When `OPENAI_API_KEY` is set and no config file is provided, `aigw run`
will read these variables and generate configuration from them:
- `OPENAI_API_KEY`: API key for authentication (required)
- `OPENAI_BASE_URL`: Base URL for the backend (defaults to
https://api.openai.com/v1)

Key features:
- Automatic localhost to 127.0.0.1.nip.io conversion for Docker/K8s
- TLS detection based on URL scheme (https) e.g. Tetrate Agent Router
Service: https://api.router.tetrate.ai/v1
- Support for custom API path prefixes e.g. OpenRouter:
https://openrouter.ai/api/v1 or LlamaStack:
http://localhost:8321/v1/openai/v1
- Clean YAML output (omits version (path prefix) field when it's "v1")

This simplifies common use cases:
- OpenAI: `OPENAI_API_KEY=sk-your-key aigw run`
- Ollama: `OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=unused aigw run`

Here's an example:
```bash
$  OPENAI_API_KEY=sk-not-tellin go run . run
looking up the latest patch for Envoy version 1.35
1.35.3 is already downloaded
starting: /tmp/envoy-gateway/versions/1.35.3/bin/envoy in run directory /tmp/envoy-gateway/runs/1758789738364346000
[2025-09-25 16:42:18.391][48486493][warning][config] [source/server/options_impl_platform_default.cc:9] CPU number provided by HW thread count (instead of cpuset).
{"bytes_received":124,"bytes_sent":795,"connection_termination_details":null,"downstream_local_address":"127.0.0.1:1975","downstream_remote_address":"127.0.0.1:62691","duration":3635,"genai_backend_name":"default/openai/route/aigw-run/rule/0/ref/0","genai_model_name":"gpt-5-nano","genai_model_name_override":"gpt-5-nano","genai_tokens_input":21,"genai_tokens_output":268,"method":"POST","response_code":200,"start_time":"2025-09-25T08:43:07.390Z","upstream_cluster":"httproute/default/aigw-run/rule/0","upstream_host":"162.159.140.245:443","upstream_local_address":"192.168.0.108:62692","upstream_transport_failure_reason":null,"user-agent":"curl/8.14.1","x-envoy-origin-path":"/v1/chat/completions","x-request-id":"9daf1c85-f75e-4c88-a90c-f9cccf85970c"}
```

Fixes envoyproxy#1211

---------

Signed-off-by: Adrian Cole <[email protected]>
Signed-off-by: Adrian Cole <[email protected]>
Co-authored-by: Anuraag (Rag) Agrawal <[email protected]>
Co-authored-by: Takeshi Yoneda <[email protected]>

Author: 3 people

cmd/aigw/README.md

@@ -8,6 +8,14 @@
 - **aigw** (port 1975): Envoy AI Gateway CLI (standalone mode)
 - **chat-completion**: curl command making a simple chat completion
 
+The simplest way to get started is to have `aigw` generate a configuration for
+your OpenAI-compatible backend. This happens when there is no configuration
+file and at least the `OPENAI_API_KEY` environment variable is set.
+
+Here are values we use for Ollama:
+- `OPENAI_API_KEY=unused` (Ollama does not require an API key)
+- `OPENAI_BASE_URL=http://localhost:11434/v1` (host.docker.internal in Docker)
+
 1. **Start Ollama** on your host machine:
 
    Start Ollama on all interfaces, with a large context. This allows it to be

cmd/aigw/config_test.go

@@ -8,58 +8,73 @@ package main
 import (
 	"os"
 	"path/filepath"
-	"runtime"
 	"testing"
 
 	"github.com/stretchr/testify/require"
 )
 
 func TestReadConfig(t *testing.T) {
-	aiGatewayLocalPath := sourceRelativePath("ai-gateway-local.yaml")
-
 	tests := []struct {
 		name           string
 		path           string
 		envVars        map[string]string
 		expectHostname string
 		expectPort     string
+		expectError    string
 	}{
 		{
-			name:           "non default config",
-			path:           aiGatewayLocalPath,
+			name: "generates config from OpenAI env vars for localhost",
+			envVars: map[string]string{
+				"OPENAI_API_KEY":  "test-key",
+				"OPENAI_BASE_URL": "http://localhost:11434/v1",
+			},
 			expectHostname: "127.0.0.1.nip.io",
 			expectPort:     "11434",
 		},
 		{
-			name: "non default config with OPENAI_HOST OPENAI_PORT",
-			path: aiGatewayLocalPath,
+			name: "generates config from OpenAI env vars for custom host",
 			envVars: map[string]string{
-				"OPENAI_HOST": "host.docker.internal",
-				"OPENAI_PORT": "8080",
+				"OPENAI_API_KEY":  "test-key",
+				"OPENAI_BASE_URL": "http://myservice:8080/v1",
 			},
-			expectHostname: "host.docker.internal",
+			expectHostname: "myservice",
 			expectPort:     "8080",
 		},
+		{
+			name: "defaults to OpenAI when only API key is set",
+			envVars: map[string]string{
+				"OPENAI_API_KEY": "test-key",
+			},
+			expectHostname: "api.openai.com",
+			expectPort:     "443",
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
+			// Clear any existing env vars
+			t.Setenv("OPENAI_API_KEY", "")
+			t.Setenv("OPENAI_BASE_URL", "")
+
 			for k, v := range tt.envVars {
 				t.Setenv(k, v)
 			}
 
 			config, err := readConfig(tt.path)
-			require.NoError(t, err)
-			require.Contains(t, config, "hostname: "+tt.expectHostname)
-			require.Contains(t, config, "port: "+tt.expectPort)
+			if tt.expectError != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.expectError)
+			} else {
+				require.NoError(t, err)
+				require.Contains(t, config, "hostname: "+tt.expectHostname)
+				require.Contains(t, config, "port: "+tt.expectPort)
+			}
 		})
 	}
 
-	// Historical configuration used an IP for ollama. We can't use this
-	// config in docker, as it needs a hostname. However, we have another
-	// config to use in docker, ai-gateway-local.yaml. So, we leave this
-	// one alone.
-	t.Run("Default config uses 0.0.0.0 IP for Ollama", func(t *testing.T) {
+	t.Run("Default config uses 0.0.0.0 IP for Ollama when no env vars", func(t *testing.T) {
+		t.Setenv("OPENAI_API_KEY", "")
+		t.Setenv("OPENAI_BASE_URL", "")
 		config, err := readConfig("")
 		require.NoError(t, err)
 		require.Contains(t, config, "address: 0.0.0.0")
@@ -166,9 +181,3 @@ func TestMaybeResolveHome(t *testing.T) {
 		})
 	}
 }
-
-func sourceRelativePath(file string) string {
-	_, filename, _, _ := runtime.Caller(0)
-	testDir := filepath.Dir(filename)
-	return filepath.Join(testDir, file)
-}

cmd/aigw/docker-compose-otel.yaml

@@ -58,15 +58,14 @@ services:
     env_file:
       - .env.otel.${COMPOSE_PROFILES:-console}
     environment:
-      - OPENAI_HOST=host.docker.internal
+      - OPENAI_BASE_URL=http://host.docker.internal:11434/v1
+      - OPENAI_API_KEY=unused
     ports:
       - "1975:1975"  # OpenAI compatible endpoint at /v1
       - "1064:1064"  # Prometheus endpoint at /metrics
     extra_hosts:  # localhost:host-gateway trick doesn't work with aigw
       - "host.docker.internal:host-gateway"
-    volumes:
-      - ./ai-gateway-local.yaml:/config.yaml:ro
-    command: ["run", "/config.yaml"]
+    command: ["run"]
 
   # chat-completion is the standard OpenAI client (`openai` in pip), instrumented
   # with the following OpenTelemetry instrumentation libraries:

cmd/aigw/docker-compose.yaml

@@ -34,15 +34,14 @@ services:
       ollama-pull:
         condition: service_completed_successfully
     environment:
-      - OPENAI_HOST=host.docker.internal
+      - OPENAI_BASE_URL=http://host.docker.internal:11434/v1
+      - OPENAI_API_KEY=unused
     ports:
       - "1975:1975"  # OpenAI compatible endpoint at /v1
       - "1064:1064"  # Prometheus endpoint at /metrics
     extra_hosts:  # localhost:host-gateway trick doesn't work with aigw
       - "host.docker.internal:host-gateway"
-    volumes:
-      - ./ai-gateway-local.yaml:/config.yaml:ro
-    command: ["run", "/config.yaml"]
+    command: ["run"]
 
   # chat-completion is a simple curl-based test client for sending requests to aigw.
   chat-completion:
@@ -63,3 +62,5 @@ services:
           -H "Authorization: Bearer unused" \
           -H "Content-Type: application/json" \
           -d "{\"model\":\"$$CHAT_MODEL\",\"messages\":[{\"role\":\"user\",\"content\":\"Answer in up to 3 words: Which ocean contains Bouvet Island?\"}]}"
+    extra_hosts:  # localhost:host-gateway trick doesn't work with aigw
+      - "host.docker.internal:host-gateway"

cmd/aigw/run.go

@@ -34,6 +34,7 @@ import (
 	"sigs.k8s.io/yaml"
 
 	"github.com/envoyproxy/ai-gateway/internal/controller"
+	"github.com/envoyproxy/ai-gateway/internal/envgen"
 	"github.com/envoyproxy/ai-gateway/internal/extensionserver"
 	"github.com/envoyproxy/ai-gateway/internal/filterapi"
 )
@@ -247,18 +248,27 @@ func pollEnvoyReadiness(ctx context.Context, l *slog.Logger, addr string, interv
 	}
 }
 
-// readConfig returns config from the given path, substituting ENV variables
-// similar to `envsubst`. If the path is empty the default config is returned.
+// readConfig reads and returns the configuration as a string from the specified path,
+// substituting environment variables similar to envsubst. If the path is empty and
+// OPENAI_API_KEY is set, it generates the configuration from OpenAI environment variables.
+// If the path is empty and no OPENAI_API_KEY is set, it returns the default configuration.
+// An error is returned if the file cannot be read or if config generation fails.
 func readConfig(path string) (string, error) {
 	if path == "" {
+		if os.Getenv("OPENAI_API_KEY") != "" {
+			config, err := envgen.GenerateOpenAIConfig()
+			if err != nil {
+				return "", fmt.Errorf("error generating OpenAI config: %w", err)
+			}
+			return config, nil
+		}
 		return aiGatewayDefaultResources, nil
 	}
-	var yamlBytes []byte
-	yamlBytes, err := envsubst.ReadFile(path)
+	configBytes, err := envsubst.ReadFile(path)
 	if err != nil {
 		return "", fmt.Errorf("error reading config: %w", err)
 	}
-	return string(yamlBytes), nil
+	return string(configBytes), nil
 }
 
 // recreateDir removes the directory at the given path and creates a new one.

internal/envgen/config.go

@@ -0,0 +1,115 @@
+// Copyright Envoy AI Gateway Authors
+// SPDX-License-Identifier: Apache-2.0
+// The full text of the Apache license is available in the LICENSE file at
+// the root of the repo.
+
+package envgen
+
+import (
+	"bytes"
+	_ "embed"
+	"fmt"
+	"net/url"
+	"os"
+	"strings"
+	"text/template"
+)
+
+//go:embed config.yaml.tmpl
+var configTemplate string
+
+// ConfigData holds the template data for generating the configuration.
+type ConfigData struct {
+	Hostname         string // Hostname for the backend (may be modified for localhost)
+	OriginalHostname string // Original hostname for TLS validation
+	Port             string // Port number as string
+	Version          string // API version path prefix (empty for "v1" to keep output clean)
+	NeedsTLS         bool   // Whether to generate BackendTLSPolicy (port 443)
+}
+
+// GenerateOpenAIConfig generates the AI Gateway configuration for a single
+// OpenAI-compatible backend, using standard OpenAI SDK environment variables.
+//
+// This errs if OPENAI_API_KEY is not set.
+//
+// See https://github.com/openai/openai-python/blob/main/src/openai/_client.py
+func GenerateOpenAIConfig() (string, error) {
+	// Check for required API key
+	if os.Getenv("OPENAI_API_KEY") == "" {
+		return "", fmt.Errorf("OPENAI_API_KEY environment variable is required")
+	}
+
+	// Get base URL with default
+	baseURL := os.Getenv("OPENAI_BASE_URL")
+	if baseURL == "" {
+		baseURL = "https://api.openai.com/v1"
+	}
+
+	// Parse URL to extract components
+	data, err := parseURL(baseURL)
+	if err != nil {
+		return "", err
+	}
+
+	// Parse and execute template
+	tmpl, err := template.New("config").Parse(configTemplate)
+	if err != nil {
+		return "", fmt.Errorf("failed to parse template: %w", err)
+	}
+
+	var buf bytes.Buffer
+	if err := tmpl.Execute(&buf, data); err != nil {
+		return "", fmt.Errorf("failed to execute template: %w", err)
+	}
+
+	return buf.String(), nil
+}
+
+// parseURL extracts hostname, port, and version from the base URL.
+func parseURL(baseURL string) (*ConfigData, error) {
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		return nil, fmt.Errorf("invalid OPENAI_BASE_URL: %w", err)
+	}
+
+	// Extract hostname
+	hostname := u.Hostname()
+	if hostname == "" {
+		return nil, fmt.Errorf("invalid OPENAI_BASE_URL: missing hostname")
+	}
+	originalHostname := hostname
+
+	// Convert localhost/127.0.0.1 to nip.io for Docker/K8s compatibility
+	if hostname == "localhost" || hostname == "127.0.0.1" {
+		hostname = "127.0.0.1.nip.io"
+	}
+
+	// Determine port
+	port := u.Port()
+	if port == "" {
+		switch u.Scheme {
+		case "https":
+			port = "443"
+		case "http":
+			port = "80"
+		default:
+			return nil, fmt.Errorf("invalid OPENAI_BASE_URL: unsupported scheme %q", u.Scheme)
+		}
+	}
+
+	// Extract version from path
+	// Strip leading slash and use the entire path as version
+	version := strings.TrimPrefix(u.Path, "/")
+	// For cleaner output, omit version field when it's just "v1"
+	if version == "v1" {
+		version = ""
+	}
+
+	return &ConfigData{
+		Hostname:         hostname,
+		OriginalHostname: originalHostname,
+		Port:             port,
+		Version:          version,
+		NeedsTLS:         u.Scheme == "https",
+	}, nil
+}