[Frontend] Gate scale-out endpoints behind opt-in flag

docs/serving/online_serving/renderer.md

@@ -6,6 +6,19 @@ Our renderer API is designed to disaggregate the render phase(preprocessing) and
 - Disaggregated tokenization: Support use cases such as llm-d, Dynamo, and custom frontends that need to leverage vLLM's preprocessing logic without running the full inference engine.
 - Tokens-in / tokens-out engine: Make the engine a pure token-in / token-out service, decoupled from request preprocessing.
 
+The dedicated `vllm launch render` server always exposes the `/render` and
+`/derender` endpoints when `VLLM_ENABLE_SCALE_OUT_ENDPOINTS` is unset or set to
+`1`. An explicit value of `0` conflicts with the renderer command and is
+rejected at startup.
+
+Scale-out endpoints, including `/render`, `/derender`, and
+`/inference/v1/generate`, are disabled by default on a standard inference
+server. To expose them with `vllm serve`, opt in explicitly:
+
+```bash
+VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1 vllm serve <model>
+```
+
 ## API Reference
 
 - [Completions Render API](renderer.md) (`/v1/completions/render`)

docs/usage/security.md

@@ -152,6 +152,16 @@ The `--api-key` flag (or `VLLM_API_KEY` environment variable) provides authentic
 
 ### Protected Endpoints (Require API Key)
 
+The scale-out `/render`, `/derender`, and `/inference/v1/generate` endpoints are
+registered on `vllm serve` only when `VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1`. The
+dedicated `vllm launch render` server registers the render and derender
+endpoints when this environment variable is unset or set to `1`; an explicit
+value of `0` is rejected. When registered, these endpoints use the same API key
+authentication as the other protected endpoints below.
+
+This setting does not disable `/v1/tokenize`, which remains available and
+shares parts of the request preprocessing path used by the render endpoints.
+
 When `--api-key` is configured, the following `/v1` endpoints require Bearer token authentication:
 
 - `/v1/models` - List available models

tests/entrypoints/scale_out/test_factories.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+
+from argparse import Namespace
+
+import pytest
+from fastapi import FastAPI
+
+from vllm.entrypoints.launchers.api_server.routers import register_api_routers
+from vllm.tasks import SupportedTask
+
+RENDER_PATHS = {
+    "/v1/chat/completions/render",
+    "/v1/chat/completions/derender",
+    "/v1/completions/render",
+    "/v1/completions/derender",
+    "/v1/messages/render",
+}
+GENERATE_PATH = "/inference/v1/generate"
+SCALE_OUT_PATHS = RENDER_PATHS | {GENERATE_PATH}
+
+
+def registered_paths(supported_tasks: tuple[SupportedTask, ...]) -> set[str]:
+    app = FastAPI()
+    args = Namespace(tokens_only=False, enable_fault_tolerance=False)
+    app.state.args = args
+    register_api_routers(args, app, supported_tasks)
+    return {route.path for route in app.routes}
+
+
+def test_scale_out_routes_are_disabled_by_default(monkeypatch):
+    monkeypatch.delenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", raising=False)
+
+    paths = registered_paths(("generate",))
+
+    assert SCALE_OUT_PATHS.isdisjoint(paths)
+
+
+def test_scale_out_routes_can_be_enabled_for_generate_server(monkeypatch):
+    monkeypatch.setenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", "1")
+
+    paths = registered_paths(("generate",))
+
+    assert paths >= SCALE_OUT_PATHS
+
+
+def test_render_routes_remain_enabled_for_render_server(monkeypatch):
+    monkeypatch.delenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", raising=False)
+
+    paths = registered_paths(("render",))
+
+    assert paths >= RENDER_PATHS
+    assert GENERATE_PATH not in paths
+
+
+def test_render_server_rejects_explicitly_disabled_scale_out_routes(monkeypatch):
+    monkeypatch.setenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", "0")
+
+    with pytest.raises(ValueError, match="VLLM_ENABLE_SCALE_OUT_ENDPOINTS=0"):
+        registered_paths(("render",))

tests/test_envs.py

@@ -43,6 +43,23 @@ def test_api_key_is_not_compile_factor(monkeypatch: pytest.MonkeyPatch):
     assert "VLLM_API_KEY" not in envs.compile_factors()
 
 
+def test_scale_out_endpoints_flag_is_runtime_only(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", "1")
+
+    assert envs.VLLM_ENABLE_SCALE_OUT_ENDPOINTS is True
+    assert "VLLM_ENABLE_SCALE_OUT_ENDPOINTS" not in envs.compile_factors()
+
+
+def test_scale_out_endpoints_flag_distinguishes_unset_from_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    monkeypatch.delenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", raising=False)
+    assert envs.VLLM_ENABLE_SCALE_OUT_ENDPOINTS is None
+
+    monkeypatch.setenv("VLLM_ENABLE_SCALE_OUT_ENDPOINTS", "0")
+    assert envs.VLLM_ENABLE_SCALE_OUT_ENDPOINTS is False
+
+
 def test_p2p_side_channel_defaults_and_override(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.delenv("VLLM_P2P_SIDE_CHANNEL_HOST", raising=False)
     monkeypatch.delenv("VLLM_P2P_SIDE_CHANNEL_PORT", raising=False)

vllm/entrypoints/launchers/api_server/routers.py

@@ -49,7 +49,15 @@ def register_api_routers(
 
         elastic_ep_attach_router(app)
 
-    if "generate" in supported_tasks or "render" in supported_tasks:
+    if "render" in supported_tasks and envs.VLLM_ENABLE_SCALE_OUT_ENDPOINTS is False:
+        raise ValueError(
+            "`VLLM_ENABLE_SCALE_OUT_ENDPOINTS=0` conflicts with "
+            "`vllm launch render`; unset it or set it to 1"
+        )
+
+    if "render" in supported_tasks or (
+        "generate" in supported_tasks and envs.VLLM_ENABLE_SCALE_OUT_ENDPOINTS
+    ):
         from vllm.entrypoints.scale_out.factories import register_scale_out_api_routers
 
         register_scale_out_api_routers(app, supported_tasks)

vllm/envs.py

@@ -260,6 +260,7 @@
     VLLM_ALLOW_CHUNKED_LOCAL_ATTN_WITH_HYBRID_KV_CACHE: bool = True
     VLLM_ENABLE_RESPONSES_API_STORE: bool = False
     VLLM_ENABLE_COHERE_API: bool = False
+    VLLM_ENABLE_SCALE_OUT_ENDPOINTS: bool | None = None
     VLLM_HAS_FLASHINFER_CUBIN: bool = False
     VLLM_ROCM_FP8_MFMA_PAGE_ATTN: bool = False
     VLLM_ALLREDUCE_USE_SYMM_MEM: bool = True
@@ -1852,6 +1853,14 @@ def _resolve_rust_cli_path() -> str | None:
     "VLLM_ENABLE_COHERE_API": lambda: bool(
         int(os.getenv("VLLM_ENABLE_COHERE_API", "0"))
     ),
+    # If set to 1, expose the scale-out endpoints on `vllm serve`.
+    # The dedicated `vllm launch render` server exposes render and derender
+    # endpoints when this variable is unset or set to 1.
+    "VLLM_ENABLE_SCALE_OUT_ENDPOINTS": lambda: (
+        bool(int(os.environ["VLLM_ENABLE_SCALE_OUT_ENDPOINTS"]))
+        if "VLLM_ENABLE_SCALE_OUT_ENDPOINTS" in os.environ
+        else None
+    ),
     # If set, use the fp8 mfma in rocm paged attention.
     "VLLM_ROCM_FP8_MFMA_PAGE_ATTN": lambda: bool(
         int(os.getenv("VLLM_ROCM_FP8_MFMA_PAGE_ATTN", "0"))
@@ -2273,6 +2282,7 @@ def compile_factors() -> dict[str, object]:
         "VLLM_CONFIG_ROOT",
         "LD_LIBRARY_PATH",
         "VLLM_SERVER_DEV_MODE",
+        "VLLM_ENABLE_SCALE_OUT_ENDPOINTS",
         "VLLM_DP_MASTER_IP",
         "VLLM_DP_MASTER_PORT",
         "VLLM_NIXL_SIDE_CHANNEL_HOST",