Summary

cao-server ships with three hardcoded loopback-only allowlists:

• ALLOWED_HOSTS — Host header allowlist for TrustedHostMiddleware
• CORS_ORIGINS — browser origins permitted by CORS
• The WebSocket PTY client_host check in terminal_ws

That posture is correct for the default install. It breaks two real workflows that the linked issues describe:

• [bug] WebSocket PTY rejects connections from Docker bridge IPs #149 — running cao-server inside a container with --host 0.0.0.0. The host browser connects via a Docker bridge IP (e.g. 172.17.0.1), which fails the hardcoded loopback check on the WebSocket endpoint, so the web UI cannot attach to any terminal.
• [feat] Make CORS origins configurable #151 — serving the UI from a non-default port or a custom origin. The hardcoded CORS_ORIGINS list rejects the browser's Origin header.

The constants.py block above ALLOWED_HOSTS already documented this as a "future extension point" mentioning CAO_ALLOWED_HOSTS — this PR wires that up and adds matching CORS and WebSocket overrides.

Changes

• constants.py — new _split_env_list() helper. ALLOWED_HOSTS, CORS_ORIGINS, and a new WS_ALLOWED_CLIENTS constant now extend their built-in defaults with comma-separated entries from CAO_ALLOWED_HOSTS, CAO_CORS_ORIGINS, and CAO_WS_ALLOWED_CLIENTS respectively.
• api/main.py — the WebSocket terminal_ws endpoint reads WS_ALLOWED_CLIENTS instead of its inline tuple. The close reason is generalised from "restricted to localhost" to "restricted to allowed clients".
• docs/settings.md — new Server Network Settings section documenting the three env vars, with an example for the Docker scenario and a security note about the unauthenticated WebSocket endpoint.

The override pattern matches the existing CAO_PROFILE_ALLOWED_HOSTS extension in install_service._allowed_download_hosts(), so contributors familiar with that path will recognise it.

Security posture

• Defaults are unchanged. An operator that does not set any of the three env vars sees the same loopback-only behavior as before.
• Extends, never replaces. Setting CAO_WS_ALLOWED_CLIENTS=172.17.0.1 keeps 127.0.0.1, ::1, and localhost allowed. This is intentional — replace-semantics (as in _allowed_download_hosts()) is easy to misuse by locking out loopback.
• The WebSocket endpoint remains unauthenticated, so the docs section calls out that the env var should only list IPs the operator actually trusts.

Test plan

• uv run pytest test/test_constants.py test/api/test_terminals.py -v — 54/54 pass, including 5 new env-var-override tests and 2 new direct-call WebSocket allowlist tests.
• Full unit suite — uv run pytest test/ --ignore=test/e2e -m "not integration" — 1713 passed, 1 skipped on Python 3.10, 3.11, and 3.12 (the CI matrix).
• uv run black --check src/ test/ — clean.
• uv run isort --check-only src/ test/ — clean.
• uv run mypy src/cli_agent_orchestrator/constants.py src/cli_agent_orchestrator/api/main.py — clean (no new findings on the changed modules).

The new WebSocket tests intentionally bypass TestClient.websocket_connect and call the endpoint coroutine directly with an AsyncMock websocket. Starlette's TestClient maps both pre-accept and post-accept close into the same WebSocketDenialResponse, so it cannot distinguish a 4003 allowlist rejection from a 4004 metadata-not-found close after accept. Driving the coroutine directly keeps the assertion precise: accept is called or not, and close.code is exactly 4003 or 4004. The existing test_websocket_rejects_non_loopback integration test (which only asserts that some exception fires) is left in place as a smoke test.

Closes #149.
Partially addresses #151 (the WebSocket and CORS gaps).