[codex] Support regex CORS origins (#3664)

Co-authored-by: Graham Neubig <398875+neubig@users.noreply.github.com>
Co-authored-by: openhands <openhands@all-hands.dev>

Author: neubig

openhands-agent-server/openhands/agent_server/README.md

@@ -54,6 +54,7 @@ The server can be configured using environment variables or a JSON configuration
 | `OPENHANDS_AGENT_SERVER_CONFIG_PATH` | Path to JSON configuration file | `workspace/openhands_agent_server_config.json` |
 | `SESSION_API_KEY` | API key for authentication (optional) | None |
 | `OH_SECRET_KEY` | Secret key for encrypting sensitive data (LLM API keys, secrets) in stored conversations. **Required for persistence across restarts.** | None |
+| `OH_ALLOW_CORS_ORIGIN_REGEX` | Regular expression for additional allowed CORS origins. Use `https?://.+` to allow any HTTP(S) origin while echoing the concrete origin. | None |
 
 ### Configuration File
 
@@ -63,6 +64,7 @@ Create a JSON configuration file (default: `workspace/openhands_agent_server_con
 {
   "session_api_key": "your-secret-api-key",
   "allow_cors_origins": ["https://your-frontend.com"],
+  "allow_cors_origin_regex": null,
   "conversations_path": "workspace/conversations",
   "webhooks": [
     {
@@ -83,6 +85,7 @@ Create a JSON configuration file (default: `workspace/openhands_agent_server_con
 
 - **`session_api_key`**: Optional API key for securing the server. If set, all requests must include this key in the `Authorization` header as `Bearer <key>`
 - **`allow_cors_origins`**: List of allowed CORS origins (localhost is always allowed)
+- **`allow_cors_origin_regex`**: Regular expression for additional allowed CORS origins. Use `https?://.+` to allow any HTTP(S) origin while keeping credential-compatible origin echoing.
 - **`webhooks`**: Array of webhook configurations for event notifications
 
 **Note**: Directory configuration (`working_dir`) will be handled at the conversation level rather than globally. These directories are specified when starting a conversation through the API.

openhands-agent-server/openhands/agent_server/api.py

@@ -556,7 +556,11 @@ def create_app(config: Config | None = None) -> FastAPI:
 
     _add_api_routes(app, config)
     _setup_static_files(app, config)
-    app.add_middleware(CORSDispatcher, allow_origins=config.allow_cors_origins)
+    app.add_middleware(
+        CORSDispatcher,
+        allow_origins=config.allow_cors_origins,
+        allow_origin_regex=config.allow_cors_origin_regex,
+    )
     _add_exception_handlers(app)
 
     return app

openhands-agent-server/openhands/agent_server/config.py

@@ -1,18 +1,27 @@
+import json
 import logging
 import os
 from pathlib import Path
-from typing import ClassVar
+from typing import Any, ClassVar
 
 from pydantic import BaseModel, ConfigDict, Field, SecretStr
 
-from openhands.agent_server.env_parser import from_env
+from openhands.agent_server.env_parser import (
+    MISSING,
+    _get_default_parsers,
+    from_env,  # noqa: F401 - compatibility re-export
+    get_env_parser,
+    merge,
+)
 from openhands.sdk.utils.cipher import Cipher
 
 
 # Environment variable constants
 V0_SESSION_API_KEY_ENV = "SESSION_API_KEY"
 V1_SESSION_API_KEY_ENV = "OH_SESSION_API_KEYS_0"
 ENVIRONMENT_VARIABLE_PREFIX = "OH"
+CONFIG_PATH_ENV = "OPENHANDS_AGENT_SERVER_CONFIG_PATH"
+DEFAULT_CONFIG_PATH = Path("workspace/openhands_agent_server_config.json")
 _logger = logging.getLogger(__name__)
 
 
@@ -126,6 +135,15 @@ class Config(BaseModel):
             "``middleware.py``."
         ),
     )
+    allow_cors_origin_regex: str | None = Field(
+        default=None,
+        description=(
+            "Regular expression matching additional CORS origins permitted by "
+            "this server. Localhost / 127.0.0.1 and ``DOCKER_HOST_ADDR`` are "
+            "always allowed. Does not apply to the workspace cookie routes, "
+            "which accept any origin — see ``middleware.py``."
+        ),
+    )
     conversations_path: Path = Field(
         default=Path("workspace/conversations"),
         description=(
@@ -239,11 +257,43 @@ def cipher(self) -> Cipher | None:
 _default_config: Config | None = None
 
 
+def _read_config_file(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text())
+    if not isinstance(data, dict):
+        raise ValueError(f"Config file must contain a JSON object: {path}")
+    return data
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    """Load agent-server config from JSON file and environment variables.
+
+    Values from ``OH_*`` environment variables override values from the JSON
+    config file so deployment-specific environment overrides keep working.
+    """
+    resolved_path = config_path
+    if resolved_path is None:
+        resolved_path = Path(os.getenv(CONFIG_PATH_ENV, DEFAULT_CONFIG_PATH))
+
+    file_data = _read_config_file(resolved_path)
+    parser = get_env_parser(Config, _get_default_parsers())
+    env_data = parser.from_env(ENVIRONMENT_VARIABLE_PREFIX)
+
+    if env_data is MISSING:
+        data = file_data
+    else:
+        data = merge(file_data, env_data)
+
+    if not data:
+        return Config()
+    return Config.model_validate(data)
+
+
 def get_default_config() -> Config:
     """Get the default local server config shared across the server"""
     global _default_config
     if _default_config is None:
-        # Get the config from the environment variables
-        _default_config = from_env(Config, ENVIRONMENT_VARIABLE_PREFIX)
+        _default_config = load_config()
         assert _default_config is not None
     return _default_config

openhands-agent-server/openhands/agent_server/middleware.py

@@ -8,8 +8,9 @@
   the request Origin on every response. These are the only routes that
   authenticate via an ambient (cookie) credential.
 * Everything else — ``LocalhostCORSMiddleware``, which honors the
-  operator's ``allow_cors_origins`` and always allows localhost and
-  ``DOCKER_HOST_ADDR`` (matches OpenHands/OpenHands#4624 intent).
+  operator's ``allow_cors_origins`` / ``allow_cors_origin_regex`` and always
+  allows localhost and ``DOCKER_HOST_ADDR`` (matches OpenHands/OpenHands#4624
+  intent).
 """
 
 import os
@@ -33,10 +34,16 @@ def _is_workspace_cookie_path(path: str) -> bool:
 class LocalhostCORSMiddleware(CORSMiddleware):
     """``CORSMiddleware`` that always allows localhost and ``DOCKER_HOST_ADDR``."""
 
-    def __init__(self, app: ASGIApp, allow_origins: list[str]) -> None:
+    def __init__(
+        self,
+        app: ASGIApp,
+        allow_origins: list[str],
+        allow_origin_regex: str | None = None,
+    ) -> None:
         super().__init__(
             app,
             allow_origins=allow_origins,
+            allow_origin_regex=allow_origin_regex,
             allow_credentials=True,
             allow_methods=["*"],
             allow_headers=["*"],
@@ -69,9 +76,17 @@ class CORSDispatcher:
        partition key and are not legitimate clients.
     """
 
-    def __init__(self, app: ASGIApp, *, allow_origins: list[str]) -> None:
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        allow_origins: list[str],
+        allow_origin_regex: str | None = None,
+    ) -> None:
         self._default_cors = LocalhostCORSMiddleware(
-            app, allow_origins=list(allow_origins)
+            app,
+            allow_origins=list(allow_origins),
+            allow_origin_regex=allow_origin_regex,
         )
         self._workspace_cors = CORSMiddleware(
             app,

tests/agent_server/test_cors.py

@@ -8,7 +8,7 @@
 from fastapi.testclient import TestClient
 
 from openhands.agent_server.api import create_app
-from openhands.agent_server.config import Config
+from openhands.agent_server.config import Config, load_config
 from openhands.agent_server.conversation_service import ConversationService
 from openhands.agent_server.dependencies import (
     WORKSPACE_SESSION_COOKIE_NAME,
@@ -194,6 +194,64 @@ def test_non_workspace_routes_reject_unlisted_origin(tmp_path):
     assert "access-control-allow-origin" not in resp.headers
 
 
+def test_non_workspace_regex_echoes_http_origin_on_actual_response(tmp_path):
+    """Regex origin matches must remain credential-compatible.
+
+    Starlette's regex path echoes the concrete origin instead of emitting a
+    literal wildcard, so browsers accept the response together with
+    ``Access-Control-Allow-Credentials: true``.
+    """
+    client = _build_client(
+        tmp_path,
+        conversation_id=uuid4(),
+        config=Config(
+            session_api_keys=[SESSION_KEY],
+            allow_cors_origin_regex=r"https?://.+",
+        ),
+    )
+
+    resp = client.get("/server_info", headers={"Origin": OTHER_ORIGIN})
+
+    assert resp.status_code == 200
+    assert resp.headers["access-control-allow-origin"] == OTHER_ORIGIN
+    assert resp.headers["access-control-allow-credentials"] == "true"
+    assert "Origin" in resp.headers.get("vary", "")
+
+
+def test_json_config_regex_echoes_http_origin_on_actual_response(tmp_path):
+    config_path = tmp_path / "config.json"
+    config_path.write_text(
+        '{"allow_cors_origin_regex": "https://.*\\\\.example\\\\.com"}'
+    )
+    client = _build_client(
+        tmp_path,
+        conversation_id=uuid4(),
+        config=load_config(config_path),
+    )
+
+    resp = client.get("/server_info", headers={"Origin": "https://app.example.com"})
+
+    assert resp.status_code == 200
+    assert resp.headers["access-control-allow-origin"] == "https://app.example.com"
+    assert resp.headers["access-control-allow-credentials"] == "true"
+    assert "Origin" in resp.headers.get("vary", "")
+
+
+def test_non_workspace_regex_rejects_null_origin(tmp_path):
+    client = _build_client(
+        tmp_path,
+        conversation_id=uuid4(),
+        config=Config(
+            session_api_keys=[SESSION_KEY],
+            allow_cors_origin_regex=r"https?://.+",
+        ),
+    )
+
+    resp = _preflight(client, "/api/conversations", origin="null")
+
+    assert "access-control-allow-origin" not in resp.headers
+
+
 def test_workspace_wildcard_does_not_bleed_into_other_api(tmp_path):
     client = _build_client(
         tmp_path, conversation_id=uuid4(), config=Config(session_api_keys=[SESSION_KEY])

tests/agent_server/test_env_parser.py

@@ -21,7 +21,7 @@
 import pytest
 from pydantic import BaseModel, Field
 
-from openhands.agent_server.config import Config
+from openhands.agent_server.config import Config, load_config
 from openhands.agent_server.env_parser import (
     MISSING,
     BoolEnvParser,
@@ -441,6 +441,7 @@ def test_config_class_parsing(clean_env):
     os.environ["OH_SESSION_API_KEYS_0"] = "key1"
     os.environ["OH_SESSION_API_KEYS_1"] = "key2"
     os.environ["OH_ALLOW_CORS_ORIGINS_0"] = "http://localhost:3000"
+    os.environ["OH_ALLOW_CORS_ORIGIN_REGEX"] = r"https://.*\.example\.com"
     os.environ["OH_CONVERSATIONS_PATH"] = "/custom/conversations"
     os.environ["OH_WORKSPACE_PATH"] = "/custom/workspace"
     os.environ["OH_ENABLE_VSCODE"] = "false"
@@ -449,11 +450,58 @@ def test_config_class_parsing(clean_env):
 
     assert config.session_api_keys == ["key1", "key2"]
     assert config.allow_cors_origins == ["http://localhost:3000"]
+    assert config.allow_cors_origin_regex == r"https://.*\.example\.com"
     assert config.conversations_path == Path("/custom/conversations")
     assert config.workspace_path == Path("/custom/workspace")
     assert config.enable_vscode is False
 
 
+def test_config_file_parsing(tmp_path, clean_env):
+    """JSON config files should populate the same Config fields as env vars."""
+    config_path = tmp_path / "config.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "session_api_keys": ["file-key"],
+                "allow_cors_origins": ["https://frontend.example.com"],
+                "allow_cors_origin_regex": r"https://.*\.example\.com",
+                "conversations_path": str(tmp_path / "conversations"),
+                "workspace_path": str(tmp_path / "workspace"),
+                "enable_vscode": False,
+            }
+        )
+    )
+
+    config = load_config(config_path)
+
+    assert config.session_api_keys == ["file-key"]
+    assert config.allow_cors_origins == ["https://frontend.example.com"]
+    assert config.allow_cors_origin_regex == r"https://.*\.example\.com"
+    assert config.conversations_path == tmp_path / "conversations"
+    assert config.workspace_path == tmp_path / "workspace"
+    assert config.enable_vscode is False
+
+
+def test_config_file_parsing_with_env_override(tmp_path, clean_env):
+    """Environment variables should override JSON config file values."""
+    config_path = tmp_path / "config.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "allow_cors_origins": ["https://file.example.com"],
+                "allow_cors_origin_regex": r"https://file\\..+",
+            }
+        )
+    )
+    os.environ["OH_ALLOW_CORS_ORIGINS_0"] = "https://env.example.com"
+    os.environ["OH_ALLOW_CORS_ORIGIN_REGEX"] = r"https://env\\..+"
+
+    config = load_config(config_path)
+
+    assert config.allow_cors_origins == ["https://env.example.com"]
+    assert config.allow_cors_origin_regex == r"https://env\\..+"
+
+
 def test_config_webhook_specs_parsing(clean_env):
     """Test parsing webhook specs in Config class."""
     # Test with JSON webhook specs