server: add --cors-* options

[ngxson]

Overview

Traditionally, llama-server always enable CORS * with no way to disable it. This was fine because llama-server endpoints were stateless, read-only and default config doesn't expose any sensitive data. The only risk was DoS which is not considered a vulnerability per llama.cpp's policy.

However, with the addition of --agent mode (built-in tools), server can now expose API that allow read/write arbitrary files. If combine with the relaxed CORS, it may allow malicious pages to access local file from server API.

This PR introduce 4 flags, inspired by vllm:

• --cors-origins
• --cors-methods
• --cors-headers
• --(no-)cors-credentials

By default:

• the relaxed profile is used: credentials are allowed and Origin header is reflected back (no breaking changes), but a warning will show when server starts
• if server tools are enable, CORS origin will be limited to localhost (can override via --cors-origins)

Recommendations

Depending on use case

• Public deployment:
  • highly recommended setting an API key
  • explicit --cors-origins is optional
  • using llama-server behind a reverse proxy to mitigate DoS-related issues
• Local (trusted) network deployment:
  • recommend explicitly set --cors-origins to origin server address
• Local deployment (same machine):
  • recommend setting --cors-origins localhost (auto set via --agent)

Requirements

• I have read and agree with the contributing guidelines
• AI usage disclosure: no

[ServeurpersoCom]

Memo to myself: I'm going to test/merge this one

[pwilkin]

@ngxson Definitely should have a separate documentation section in the server notes, at least with what you just wrote in the PR description.

[ServeurpersoCom]

@ngxson Definitely should have a separate documentation section in the server notes, at least with what you just wrote in the PR description.

I think I can commit to the branch if you approve this proposal, @pwilkin?

doc proposal :

diff --git a/tools/server/README.md b/tools/server/README.md
index 9c8b32dcc..84132b5d7 100644
--- a/tools/server/README.md
+++ b/tools/server/README.md
@@ -329,6 +329,22 @@ The server includes a set of built-in tools that enable the LLM to access the lo

 To use this feature, start the server with `--tools all`. You can also enable only specific tools by passing a comma-separated list: `--tools name1,name2,...`. Run `--help` for the full list of available tool names.

+### CORS
+
+By default the server reflects any `Origin` header back with credentials allowed. This matches the old, always-on `*` behavior and is fine as long as the server only exposes stateless, read-only endpoints.
+
+Enabling `--tools` or `--agent` exposes file read/write over the API, so in that case `--cors-origins` defaults to `localhost` instead: only pages served from localhost can reach the server. Pass `--cors-origins` explicitly to override either default.
+
+Recommended `--cors-origins` setting, depending on where the server runs:
+
+| Deployment | Recommendation |
+| ---------- | --------------- |
+| Public | set an API key, put the server behind a reverse proxy, `--cors-origins` optional |
+| Local network | set `--cors-origins` to your frontend's origin |
+| Same machine | `--cors-origins localhost` (default once `--agent` is set) |
+
+Related flags: `--cors-origins`, `--cors-methods`, `--cors-headers`, `--cors-credentials` / `--no-cors-credentials`. Background and rationale: [#25655](https://github.com/ggml-org/llama.cpp/pull/25655).
+
 ## Build

 `llama-server` is built alongside everything else from the root of the project

CORS

By default the server reflects any Origin header back with credentials allowed. This matches the old, always-on * behavior and is fine as long as the server only exposes stateless, read-only endpoints.

Enabling --tools or --agent exposes file read/write over the API, so in that case --cors-origins defaults to localhost instead: only pages served from localhost can reach the server. Pass --cors-origins explicitly to override either default.

Recommended --cors-origins setting, depending on where the server runs:

Deployment	Recommendation
Public	set an API key, put the server behind a reverse proxy, --cors-origins optional
Local network	set --cors-origins to your frontend's origin
Same machine	--cors-origins localhost (default once --agent is set)

Related flags: --cors-origins, --cors-methods, --cors-headers, --cors-credentials / --no-cors-credentials. Background and rationale: #25655.

[ServeurpersoCom]

LGTM

What's I tested :

• default (*, credentials) behavior unchanged, startup warning fires

• --agent / --tools switches default to localhost, explicit override works

• reflects localhost / 127.0.0.1 / [::1], rejects everything else

• /cors-proxy forwards only explicit proxy headers

• test_security.py: 17/17 passed

• adversarial: null origin, subdomain suffix, decimal/mapped IP, case, trailing dot all rejected

• minor: "http://evil.com@localhost" accepted, host correctly parses as localhost per URL syntax, not exploitable: browsers never put userinfo in the Origin header (RFC 6454), no real request can carry this value