codex-relay-server 0.1.0__tar.gz

codex_relay_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGN_2015
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_relay_server-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: codex-relay-server
+Version: 0.1.0
+Summary: A LAN OpenAI-compatible relay server.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# codex-relay-server
+
+A LAN relay server for OpenAI-compatible HTTP APIs.
+
+Use this when one computer can reach the upstream model provider, but other computers on the LAN can only reach that computer. LAN clients point their OpenAI SDKs at this relay; the relay forwards requests to your configured upstream API root and streams the upstream response back.
+
+## Features
+
+- Bind to any local IP and port, such as `0.0.0.0:8000` or a specific LAN adapter IP.
+- Use any upstream API root URL. The upstream does not need to use `/v1`.
+- Configure the local client-facing base path, such as `/`, `/v1`, `/openai`, or `/api/openai`.
+- Forward all endpoints with the same path rules, including `/chat/completions`, `/responses`, `/models`, and future API paths.
+- Pass through normal JSON responses and streaming SSE responses.
+- Support two API key modes:
+  - `direct`: forward the incoming `Authorization` header unchanged.
+  - `transform`: map client-visible keys to upstream keys, with an optional default upstream key.
+
+## Installation
+
+```powershell
+.\venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+## Configuration
+
+Copy the example config:
+
+```powershell
+Copy-Item config.example.json config.json
+```
+
+Edit `config.json`:
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000
+  },
+  "relay": {
+    "upstream_url": "https://your-upstream.example/custom-api",
+    "local_base_path": "/",
+    "strip_local_base_path": true
+  },
+  "auth": {
+    "mode": "direct"
+  }
+}
+```
+
+With that config, an incoming LAN request to `/responses` is forwarded to:
+
+```text
+https://your-upstream.example/custom-api/responses
+```
+
+The default `local_base_path` is `/`, so the relay accepts requests from the root path. Set `local_base_path` explicitly if you want clients to use a specific base URL such as `/v1` or `/openai`.
+
+Set `strip_local_base_path` to `false` if you want the full local path appended to the upstream URL.
+
+You can expose any local base path:
+
+```json
+{
+  "relay": {
+    "upstream_url": "https://your-upstream.example/not-v1",
+    "local_base_path": "/openai",
+    "strip_local_base_path": true
+  }
+}
+```
+
+LAN clients can then use this base URL:
+
+```text
+http://<relay-lan-ip>:8000/openai
+```
+
+### Transform Mode
+
+```json
+{
+  "auth": {
+    "mode": "transform",
+    "key_map": {
+      "client-visible-key-a": "real-upstream-key-a",
+      "client-visible-key-b": "real-upstream-key-b"
+    },
+    "default_key": "real-default-upstream-key"
+  }
+}
+```
+
+In transform mode, if the client sends:
+
+```text
+Authorization: Bearer client-visible-key-a
+```
+
+The upstream receives:
+
+```text
+Authorization: Bearer real-upstream-key-a
+```
+
+If the client key is not in `key_map` and `default_key` is configured, the relay uses `default_key`. If no default key is available, the relay returns `401`.
+
+Keep real upstream keys in local `config.json` or Python-provided configuration. Do not commit them. This repository ignores `config.json`, `*.local.json`, and `*.secrets.json`.
+
+### Python Configuration
+
+You can also provide configuration from Python code instead of a JSON file:
+
+```python
+from codex_relay_server import create_app, load_settings
+
+settings = load_settings(
+    {
+        "server": {"host": "0.0.0.0", "port": 8000},
+        "relay": {
+            "upstream_url": "https://your-upstream.example/custom-api",
+            "local_base_path": "/openai",
+            "strip_local_base_path": True,
+        },
+        "auth": {"mode": "direct"},
+    }
+)
+
+app = create_app(settings)
+```
+
+## Run
+
+```powershell
+.\venv\Scripts\python.exe -m codex_relay_server --config config.json
+```
+
+You can temporarily override the bind address, port, upstream URL, and local base path:
+
+```powershell
+.\venv\Scripts\python.exe -m codex_relay_server `
+  --config config.json `
+  --host 0.0.0.0 `
+  --port 8000 `
+  --upstream-url https://your-upstream.example/custom-api `
+  --local-base-path /openai
+```
+
+LAN client settings:
+
+```text
+base_url = http://<relay-lan-ip>:8000/<your-local-base-path>
+api_key = <client-key>
+```
+
+## Tests
+
+```powershell
+.\venv\Scripts\python.exe -m pytest
+```
+
+Tests use a local mock upstream and do not need a real API key.
+
+## Security Notes
+
+- Do not expose this service to the public internet, especially in `transform` mode with `default_key` enabled.
+- If you bind to `0.0.0.0`, make sure your firewall only allows trusted LAN clients.
+- The project does not store private keys in tracked files. Put real keys in ignored local config files or Python-provided configuration.

codex_relay_server-0.1.0/README.md

@@ -0,0 +1,168 @@
+# codex-relay-server
+
+A LAN relay server for OpenAI-compatible HTTP APIs.
+
+Use this when one computer can reach the upstream model provider, but other computers on the LAN can only reach that computer. LAN clients point their OpenAI SDKs at this relay; the relay forwards requests to your configured upstream API root and streams the upstream response back.
+
+## Features
+
+- Bind to any local IP and port, such as `0.0.0.0:8000` or a specific LAN adapter IP.
+- Use any upstream API root URL. The upstream does not need to use `/v1`.
+- Configure the local client-facing base path, such as `/`, `/v1`, `/openai`, or `/api/openai`.
+- Forward all endpoints with the same path rules, including `/chat/completions`, `/responses`, `/models`, and future API paths.
+- Pass through normal JSON responses and streaming SSE responses.
+- Support two API key modes:
+  - `direct`: forward the incoming `Authorization` header unchanged.
+  - `transform`: map client-visible keys to upstream keys, with an optional default upstream key.
+
+## Installation
+
+```powershell
+.\venv\Scripts\python.exe -m pip install -e ".[dev]"
+```
+
+## Configuration
+
+Copy the example config:
+
+```powershell
+Copy-Item config.example.json config.json
+```
+
+Edit `config.json`:
+
+```json
+{
+  "server": {
+    "host": "0.0.0.0",
+    "port": 8000
+  },
+  "relay": {
+    "upstream_url": "https://your-upstream.example/custom-api",
+    "local_base_path": "/",
+    "strip_local_base_path": true
+  },
+  "auth": {
+    "mode": "direct"
+  }
+}
+```
+
+With that config, an incoming LAN request to `/responses` is forwarded to:
+
+```text
+https://your-upstream.example/custom-api/responses
+```
+
+The default `local_base_path` is `/`, so the relay accepts requests from the root path. Set `local_base_path` explicitly if you want clients to use a specific base URL such as `/v1` or `/openai`.
+
+Set `strip_local_base_path` to `false` if you want the full local path appended to the upstream URL.
+
+You can expose any local base path:
+
+```json
+{
+  "relay": {
+    "upstream_url": "https://your-upstream.example/not-v1",
+    "local_base_path": "/openai",
+    "strip_local_base_path": true
+  }
+}
+```
+
+LAN clients can then use this base URL:
+
+```text
+http://<relay-lan-ip>:8000/openai
+```
+
+### Transform Mode
+
+```json
+{
+  "auth": {
+    "mode": "transform",
+    "key_map": {
+      "client-visible-key-a": "real-upstream-key-a",
+      "client-visible-key-b": "real-upstream-key-b"
+    },
+    "default_key": "real-default-upstream-key"
+  }
+}
+```
+
+In transform mode, if the client sends:
+
+```text
+Authorization: Bearer client-visible-key-a
+```
+
+The upstream receives:
+
+```text
+Authorization: Bearer real-upstream-key-a
+```
+
+If the client key is not in `key_map` and `default_key` is configured, the relay uses `default_key`. If no default key is available, the relay returns `401`.
+
+Keep real upstream keys in local `config.json` or Python-provided configuration. Do not commit them. This repository ignores `config.json`, `*.local.json`, and `*.secrets.json`.
+
+### Python Configuration
+
+You can also provide configuration from Python code instead of a JSON file:
+
+```python
+from codex_relay_server import create_app, load_settings
+
+settings = load_settings(
+    {
+        "server": {"host": "0.0.0.0", "port": 8000},
+        "relay": {
+            "upstream_url": "https://your-upstream.example/custom-api",
+            "local_base_path": "/openai",
+            "strip_local_base_path": True,
+        },
+        "auth": {"mode": "direct"},
+    }
+)
+
+app = create_app(settings)
+```
+
+## Run
+
+```powershell
+.\venv\Scripts\python.exe -m codex_relay_server --config config.json
+```
+
+You can temporarily override the bind address, port, upstream URL, and local base path:
+
+```powershell
+.\venv\Scripts\python.exe -m codex_relay_server `
+  --config config.json `
+  --host 0.0.0.0 `
+  --port 8000 `
+  --upstream-url https://your-upstream.example/custom-api `
+  --local-base-path /openai
+```
+
+LAN client settings:
+
+```text
+base_url = http://<relay-lan-ip>:8000/<your-local-base-path>
+api_key = <client-key>
+```
+
+## Tests
+
+```powershell
+.\venv\Scripts\python.exe -m pytest
+```
+
+Tests use a local mock upstream and do not need a real API key.
+
+## Security Notes
+
+- Do not expose this service to the public internet, especially in `transform` mode with `default_key` enabled.
+- If you bind to `0.0.0.0`, make sure your firewall only allows trusted LAN clients.
+- The project does not store private keys in tracked files. Put real keys in ignored local config files or Python-provided configuration.

codex_relay_server-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-relay-server"
+version = "0.1.0"
+description = "A LAN OpenAI-compatible relay server."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "fastapi>=0.110",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "uvicorn[standard]>=0.29",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+codex-relay-server = "codex_relay_server.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+pythonpath = ["src"]

codex_relay_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codex_relay_server-0.1.0/src/codex_relay_server/__init__.py

@@ -0,0 +1,17 @@
+"""OpenAI-compatible LAN relay server."""
+
+from .config import AuthConfig, AuthMode, RelayConfig, ServerConfig, Settings, load_settings
+from .relay import create_app
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthConfig",
+    "AuthMode",
+    "RelayConfig",
+    "ServerConfig",
+    "Settings",
+    "__version__",
+    "create_app",
+    "load_settings",
+]

codex_relay_server-0.1.0/src/codex_relay_server/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

codex_relay_server-0.1.0/src/codex_relay_server/auth.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from fastapi import HTTPException, status
+
+from .config import AuthConfig, AuthMode
+
+
+def resolve_authorization_header(incoming_authorization: str | None, config: AuthConfig) -> str | None:
+    if config.mode == AuthMode.DIRECT:
+        return incoming_authorization
+
+    client_key = extract_client_key(incoming_authorization)
+    upstream_secret = config.key_map.get(client_key or "") if client_key else None
+    if upstream_secret is None:
+        upstream_secret = config.default_key
+
+    if upstream_secret is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="No upstream API key is available for this client key.",
+        )
+
+    return f"Bearer {upstream_secret.get_secret_value()}"
+
+
+def extract_client_key(authorization_header: str | None) -> str | None:
+    if authorization_header is None:
+        return None
+
+    authorization_header = authorization_header.strip()
+    if not authorization_header:
+        return None
+
+    scheme, separator, value = authorization_header.partition(" ")
+    if separator and scheme.lower() == "bearer":
+        value = value.strip()
+        return value or None
+
+    return authorization_header

codex_relay_server-0.1.0/src/codex_relay_server/cli.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+import uvicorn
+
+from .config import load_settings
+from .relay import create_app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run a LAN OpenAI-compatible relay server.")
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        default=None,
+        help="Path to a JSON config file.",
+    )
+    parser.add_argument("--host", help="Override server.host, for example 0.0.0.0 or a LAN IP.")
+    parser.add_argument("--port", type=int, help="Override server.port.")
+    parser.add_argument("--upstream-url", help="Override relay.upstream_url.")
+    parser.add_argument("--local-base-path", help="Override relay.local_base_path.")
+    parser.add_argument(
+        "--strip-local-base-path",
+        type=parse_bool,
+        help="Override relay.strip_local_base_path with true or false.",
+    )
+    parser.add_argument("--auth-mode", choices=("direct", "transform"), help="Override auth.mode.")
+    parser.add_argument("--log-level", help="Override server.log_level.")
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    settings = load_settings(args.config)
+    updates = {}
+    if args.host is not None:
+        updates.setdefault("server", {})["host"] = args.host
+    if args.port is not None:
+        updates.setdefault("server", {})["port"] = args.port
+    if args.log_level is not None:
+        updates.setdefault("server", {})["log_level"] = args.log_level
+    if args.upstream_url is not None:
+        updates.setdefault("relay", {})["upstream_url"] = args.upstream_url
+    if args.local_base_path is not None:
+        updates.setdefault("relay", {})["local_base_path"] = args.local_base_path
+    if args.strip_local_base_path is not None:
+        updates.setdefault("relay", {})["strip_local_base_path"] = args.strip_local_base_path
+    if args.auth_mode is not None:
+        updates.setdefault("auth", {})["mode"] = args.auth_mode
+    if updates:
+        settings = type(settings).model_validate(_deep_update(settings.model_dump(mode="python"), updates))
+
+    app = create_app(settings)
+    uvicorn.run(app, host=settings.server.host, port=settings.server.port, log_level=settings.server.log_level)
+
+
+def parse_bool(value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "y", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "n", "off"}:
+        return False
+    raise argparse.ArgumentTypeError(f"invalid boolean value: {value!r}")
+
+
+def _deep_update(original: dict[str, Any], updates: dict[str, Any]) -> dict[str, Any]:
+    for key, value in updates.items():
+        if isinstance(value, dict) and isinstance(original.get(key), dict):
+            original[key] = _deep_update(original[key], value)
+        else:
+            original[key] = value
+    return original

codex_relay_server-0.1.0/src/codex_relay_server/config.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from collections.abc import Mapping
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, SecretStr, field_validator, model_validator
+
+
+class AuthMode(StrEnum):
+    DIRECT = "direct"
+    TRANSFORM = "transform"
+
+
+class ServerConfig(BaseModel):
+    host: str = "127.0.0.1"
+    port: int = 8000
+    log_level: str = "info"
+
+    @field_validator("port")
+    @classmethod
+    def validate_port(cls, value: int) -> int:
+        if not 1 <= value <= 65535:
+            raise ValueError("port must be between 1 and 65535")
+        return value
+
+
+class RelayConfig(BaseModel):
+    upstream_url: str = "https://api.openai.com/v1"
+    local_base_path: str = "/"
+    strip_local_base_path: bool = True
+    timeout_seconds: float = 300
+    verify_ssl: bool = True
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_old_base_path_names(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if "local_base_path" not in data and "public_base_path" in data:
+                data["local_base_path"] = data["public_base_path"]
+            if "strip_local_base_path" not in data and "strip_public_base_path" in data:
+                data["strip_local_base_path"] = data["strip_public_base_path"]
+        return data
+
+    @field_validator("upstream_url")
+    @classmethod
+    def validate_upstream_url(cls, value: str) -> str:
+        value = value.strip()
+        if not value:
+            raise ValueError("upstream_url is required")
+        if not value.startswith(("http://", "https://")):
+            raise ValueError("upstream_url must start with http:// or https://")
+        return value.rstrip("/")
+
+    @field_validator("local_base_path")
+    @classmethod
+    def validate_local_base_path(cls, value: str) -> str:
+        value = value.strip()
+        if value in {"", "/"}:
+            return "/"
+        if not value.startswith("/"):
+            value = f"/{value}"
+        return value.rstrip("/")
+
+    @field_validator("timeout_seconds")
+    @classmethod
+    def validate_timeout(cls, value: float) -> float:
+        if value <= 0:
+            raise ValueError("timeout_seconds must be greater than 0")
+        return value
+
+
+class AuthConfig(BaseModel):
+    mode: AuthMode = AuthMode.DIRECT
+    key_map: dict[str, SecretStr] = Field(default_factory=dict)
+    default_key: SecretStr | None = None
+
+
+class Settings(BaseModel):
+    server: ServerConfig = Field(default_factory=ServerConfig)
+    relay: RelayConfig = Field(default_factory=RelayConfig)
+    auth: AuthConfig = Field(default_factory=AuthConfig)
+
+
+ConfigInput = Settings | Mapping[str, Any] | str | Path | None
+
+
+def load_settings(config: ConfigInput = None) -> Settings:
+    raw: dict[str, Any] = {}
+    if isinstance(config, Settings):
+        raw = config.model_dump(mode="python")
+    elif isinstance(config, Mapping):
+        raw = deepcopy(dict(config))
+    elif config:
+        path = Path(config)
+        if not path.exists():
+            raise FileNotFoundError(f"config file not found: {path}")
+        with path.open("r", encoding="utf-8") as file:
+            loaded = json.load(file)
+        if not isinstance(loaded, dict):
+            raise ValueError("config file must contain a JSON object")
+        raw = loaded
+
+    return Settings.model_validate(raw)