Skip to content

FreeToken brings datacenter-scale model serving to your desktop. Run massive models locally, fast and efficiently.

feat(server): add --api-key authentication (#639)

Xiaoze Fan95281904548d
diff --git a/docs/cli.md b/docs/cli.md
index b9be878c..a15a34b7 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -41,6 +41,7 @@ parsers all resolve automatically from the checkpoint and the GPU.
|---|---|---|
| `--host` | 127.0.0.1 | Bind address |
| `--port` | 1919 | Bind port |
+| `--api-key` | `$FREETOKEN_API_KEY`, else off | Require the key on every route except `/health`, as `Authorization: Bearer <key>` or `x-api-key: <key>`; other requests get a 401 |
| `--gpu` | GPU 0 | GPU to run on: a UUID from `nvidia-smi -L` or an `nvidia-smi` index; see [below](#choosing-a-gpu) |
| `--max-running-requests` | 4 | Max concurrently running requests |
| `--max-output-tokens` | 32768 | Default output budget for requests that omit one |
@@ -131,14 +132,17 @@ ft shell --model ~/models/Qwen3.6-35B-A3B # serve + chat in one process
```
- Attach mode talks to `--server URL` (default `http://127.0.0.1:1919`)
+- `--api-key KEY` (default `$FREETOKEN_API_KEY`) attaches to a server started with `--api-key`; with `--model` the shell uses that server's own key
- `/help` inside the shell lists the commands (`/think`, `/cache`, `/reset`).
## ft ctl
```bash
-ft ctl [--base-url http://127.0.0.1:1919] [--timeout 10] [--json] <subcommand>
+ft ctl [--base-url http://127.0.0.1:1919] [--api-key KEY] [--timeout 10] [--json] <subcommand>
```
+`--api-key` defaults to `$FREETOKEN_API_KEY`.
+
| Subcommand | Endpoint | Purpose |
|---|---|---|
| `health` | `GET /health` | Server status, model, load progress |
@@ -166,6 +170,7 @@ Code and Hermes need no declaration.
| Flag | Meaning |
|---|---|
| `--server URL` | Server to point the agent at (default `http://127.0.0.1:1919`) |
+| `--api-key KEY` | Key of a server started with `--api-key` (default `$FREETOKEN_API_KEY`). The agent gets it in its environment; Hermes and OpenClaw keep it in their config files |
| `--dry-run` | Print the planned config changes and command, touch nothing |
| `-y`, `--yes` | Approve install/config prompts |
| `--config` | Configure without launching |
diff --git a/python/freetoken/control_cli.py b/python/freetoken/control_cli.py
index 50a32aae..e33eb4ac 100644
--- a/python/freetoken/control_cli.py
+++ b/python/freetoken/control_cli.py
@@ -10,6 +10,8 @@ import urllib.request
from collections.abc import Sequence
from typing import Any
+from freetoken.launch import resolve_api_key
+
DEFAULT_BASE_URL = "http://127.0.0.1:1919"
# (CLI dest, pool, rebuild body key). moe/mamba are slot counts and pass straight through;
@@ -74,6 +76,7 @@ def _request_json(
body: dict[str, Any] | None = None,
query: dict[str, Any] | None = None,
timeout: float = 10.0,
+ api_key: str | None,
) -> dict[str, Any]:
with _open_request(
method,
@@ -83,6 +86,7 @@ def _request_json(
query=query,
accept="application/json",
timeout=timeout,
+ api_key=api_key,
) as response:
raw = response.read()
@@ -104,6 +108,7 @@ def _request_sse_text(
*,
body: dict[str, Any] | None = None,
timeout: float = 10.0,
+ api_key: str | None,
) -> str:
with _open_request(
method,
@@ -112,6 +117,7 @@ def _request_sse_text(
body=body,
accept="text/event-stream",
timeout=timeout,
+ api_key=api_key,
) as response:
return _read_sse_text(response)
@@ -125,9 +131,12 @@ def _open_request(
query: dict[str, Any] | None = None,
accept: str,
timeout: float,
+ api_key: str | None,
) -> Any:
data = None
headers = {"Accept": accept}
+ if api_key:
+ headers["Authorization"] = f"Bearer {api_key}"
if body is not None:
data = json.dumps(body).encode("utf-8")
headers["Content-Type"] = "application/json"
@@ -284,6 +293,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:
default=DEFAULT_BASE_URL,
help=f"FreeToken server URL (default: {DEFAULT_BASE_URL})",
)
+ parser.add_argument(
+ "--api-key",
+ help="API key of a server started with --api-key (default: $FREETOKEN_API_KEY)",
+ )
parser.add_argument("--timeout", type=float, default=10.0, help="HTTP timeout in seconds")
parser.add_argument("--json", action="store_true", help="Print raw JSON response")
@@ -355,14 +368,19 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:
args = parser.parse_args(list(argv) if argv is not None else None)
except SystemExit as exc:
return int(exc.code) if isinstance(exc.code, int) else 2
+ args.api_key = resolve_api_key(args.api_key)
try:
if args.command == "health":
- doc = _request_json("GET", args.base_url, "/health", timeout=args.timeout)
+ doc = _request_json(
+ "GET", args.base_url, "/health", timeout=args.timeout, api_key=args.api_key
+ )
_print_doc(doc, _format_health, raw_json=args.json)
return 0
if args.command == "stats":
- doc = _request_json("GET", args.base_url, "/v1/stats", timeout=args.timeout)
+ doc = _request_json(
+ "GET", args.base_url, "/v1/stats", timeout=args.timeout, api_key=args.api_key
+ )
_print_doc(doc, _format_stats, raw_json=args.json)
return 0
if args.command == "generate":
@@ -376,6 +394,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:
"ignore_eos": args.ignore_eos,
},
timeout=args.timeout,
+ api_key=args.api_key,
)
if args.json:
print(json.dumps({"text": text}, ensure_ascii=False, indent=2, sort_keys=True))
@@ -390,13 +409,16 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft ctl") -> int:
"/v1/requests",
query=query,
timeout=args.timeout,
+ api_key=args.api_key,
)
_print_doc(doc, _format_requests, raw_json=args.json)
return 0
if args.command == "cache" and args.cache_command in (None, "status"):
if args.cache_command is None and _cache_targets(args):
return _run_cache_rebuild(args)
- doc = _request_json("GET", args.base_url, "/v1/cache/status", timeout=args.timeout)
+ doc = _request_json(
+ "GET", args.base_url, "/v1/cache/status", timeout=args.timeout, api_key=args.api_key
+ )
_print_doc(doc, _format_cache_status, raw_json=args.json)
return 0
if args.command == "cache" and args.cache_command == "rebuild":
@@ -444,7 +466,9 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:
print("error: cache rebuild requires at least one cache target", file=sys.stderr)
return 2
# The token targets can only be converted against the live geometry, so read it first.
- status = _request_json("GET", args.base_url, "/v1/cache/status", timeout=args.timeout)
+ status = _request_json(
+ "GET", args.base_url, "/v1/cache/status", timeout=args.timeout, api_key=args.api_key
+ )
body = _rebuild_body(targets, status.get("geometry") or {})
body["timeout"] = args.wait
doc = _request_json(
@@ -453,6 +477,7 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:
"/v1/cache/rebuild",
body=body,
timeout=args.wait + args.timeout,
+ api_key=args.api_key,
)
if args.json or doc.get("status") != "ok":
_print_doc(doc, _format_rebuild, raw_json=args.json)
@@ -462,7 +487,9 @@ def _run_cache_rebuild(args: argparse.Namespace) -> int:
# /cache prints. Best-effort -- the rebuild already succeeded.
print("status=ok")
try:
- print(_format_cache_status(_request_json("GET", args.base_url, "/v1/cache/status")))
+ print(_format_cache_status(
+ _request_json("GET", args.base_url, "/v1/cache/status", api_key=args.api_key)
+ ))
except ControlCliError:
pass
return 0
diff --git a/python/freetoken/daemon/README.md b/python/freetoken/daemon/README.md
index ea3b016e..ebe4a170 100644
--- a/python/freetoken/daemon/README.md
+++ b/python/freetoken/daemon/README.md
@@ -60,9 +60,9 @@ Target a non-default daemon with `--url http://host:1900` (or `$FREETOKEN_DAEMON
| Method / path | Notes |
| --- | --- |
| `GET /health` | Daemon self-health; always answers, never gated by `--token`. |
-| `POST /engine/start` `{model,port,args[]}` | Idempotent on the full `(model,port,args)`; a differing config on the same port → `409`. |
+| `POST /engine/start` `{model,port,args[],apiKey?}` | Idempotent on the full `(model,port,args,apiKey)`; a differing config on the same port → `409`. |
| `POST /engine/stop` `{force?:false}` | Close admission, drain/abort, durably enqueue the final-accounting receipt, then `SIGTERM`→grace→`SIGKILL`. A prepare/outbox failure preserves the engine. |
-| `POST /engine/switch` `{model,port,args[],force?:false}` | One serialized stop-accounting-start transaction. |
+| `POST /engine/switch` `{model,port,args[],apiKey?,force?:false}` | One serialized stop-accounting-start transaction. |
| `GET /engine/status` | `{running,pid,model,port,uptimeS,lastExitCode,…}`; outlives any single serve. |
| `GET /engine/logs?since=` | SSE, ANSI-stripped, tqdm-`\r` collapsed, ring replay, `id:<seq>`, `Last-Event-ID` resume. |
| `GET /engine/metrics` | `{ramBytes,vramBytes}` — the serve tree's own footprint only. |
@@ -75,6 +75,13 @@ Target a non-default daemon with `--url http://host:1900` (or `$FREETOKEN_DAEMON
Set `--token` (or `$FREETOKEN_DAEMON_TOKEN`) to require an `X-FT-Token` header on everything
except `/health`.
+`apiKey` is the serve's own `--api-key`. The daemon hands it to the serve as `FREETOKEN_API_KEY` in
+its environment (never on its command line), sends it on its own calls to the serve, and keeps it in
+the owner-only state file so a re-adopted serve stays reachable. The daemon's own
+`FREETOKEN_API_KEY` is never passed down: a serve requires a key only when its start request carries
+one, and an `--api-key` inside `args` is rejected with a 400 because the daemon would not know it.
+`ft daemon start|switch --api-key KEY` (default `$FREETOKEN_API_KEY`) sets it.
+
The daemon reaches the serve's destructive `POST /v1/admin/prepare-stop` endpoint only over
loopback; the serve rejects non-loopback callers even when its inference API is bound to
`0.0.0.0`. `force` is never implicit: it is an explicit recovery choice that may record null
diff --git a/python/freetoken/daemon/app.py b/python/freetoken/daemon/app.py
index d7a0a53c..dd506f78 100644
--- a/python/freetoken/daemon/app.py
+++ b/python/freetoken/daemon/app.py
@@ -30,6 +30,7 @@ class StartBody(BaseModel):
model: str
port: int | None = None
args: list[str] = []
+ apiKey: str | None = None
class StopBody(BaseModel):
@@ -161,6 +162,15 @@ def build_app(
st = manager.status()
return st.get("port") or default_serve_port
+ def reject_api_key_arg(args: list[str]) -> None:
+ # the daemon must know the key to reach the serve, so the key only travels as apiKey
+ # argparse also accepts any unambiguous prefix, and no other serve flag starts with --ap
+ flags = (a.split("=", 1)[0] for a in args)
+ if any(len(f) >= 4 and "--api-key".startswith(f) for f in flags):
+ raise HTTPException(
+ status_code=400, detail="pass the serve's API key as apiKey, not in args"
+ )
+
def accounting_error(exc: Exception) -> JSONResponse:
code = (
"accounting_outbox_failed"
@@ -192,9 +202,17 @@ def build_app(
@app.post("/engine/start", dependencies=auth)
async def engine_start(body: StartBody):
+ reject_api_key_arg(body.args)
port = resolve_port(body.port)
try:
- return await run(lifecycle_pool, manager.start, body.model, port, list(body.args))
+ return await run(
+ lifecycle_pool,
+ manager.start,
+ body.model,
+ port,
+ list(body.args),
+ body.apiKey or None,
+ )
except Conflict as exc:
st = manager.status()
return JSONResponse(
@@ -236,6 +254,7 @@ def build_app(
@app.post("/engine/switch", dependencies=auth)
async def engine_switch(body: SwitchBody):
+ reject_api_key_arg(body.args)
port = resolve_port(body.port)
try:
return await run(
@@ -245,6 +264,7 @@ def build_app(
port,
list(body.args),
body.force,
+ body.apiKey or None,
)
except (AccountingPrepareError, AccountingOutboxError) as exc:
return accounting_error(exc)
diff --git a/python/freetoken/daemon/client.py b/python/freetoken/daemon/client.py
index 6616778e..9ded9627 100644
--- a/python/freetoken/daemon/client.py
+++ b/python/freetoken/daemon/client.py
@@ -16,6 +16,8 @@ import urllib.request
from collections.abc import Sequence
from typing import Any
+from freetoken.launch import resolve_api_key
+
DEFAULT_URL = "http://127.0.0.1:1900"
DEFAULT_TIMEOUT = 10.0
# prepare-stop (15s transport budget) + default SIGTERM grace (10s) + reap wait (10s),
@@ -144,6 +146,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:
sp = sub.add_parser(name, parents=[common], help=f"POST /engine/{name}")
sp.add_argument("model", help="Model path/id")
sp.add_argument("--port", type=int, default=None, help="Serve port")
+ sp.add_argument(
+ "--api-key",
+ help="API key the serve requires, set in its environment (default: $FREETOKEN_API_KEY)",
+ )
if name == "switch":
sp.add_argument(
"--force",
@@ -181,6 +187,8 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft daemon") -> int:
body: dict[str, Any] = {"model": args.model, "args": list(args.serve_args)}
if args.port is not None:
body["port"] = args.port
+ if api_key := resolve_api_key(args.api_key):
+ body["apiKey"] = api_key
if args.verb == "switch" and args.force:
body["force"] = True
method, path = "POST", f"/engine/{args.verb}"
diff --git a/python/freetoken/daemon/pidfile.py b/python/freetoken/daemon/pidfile.py
index 89ffc2b4..b9865a83 100644
--- a/python/freetoken/daemon/pidfile.py
+++ b/python/freetoken/daemon/pidfile.py
@@ -4,15 +4,16 @@
open for the daemon's whole life. flock (not a bare port-bind) avoids TIME_WAIT races and is
released automatically if the daemon dies, so a crashed daemon never wedges its own restart.
-``ServeStateStore`` persists ``{model, port, pid, args, starttime, logPath}`` as JSON on every
+``ServeStateStore`` persists ``{model, port, pid, args, starttime, log_path, api_key}`` as JSON on every
lifecycle change, so a restarted daemon can re-adopt a still-running serve. ``starttime`` +
-``args`` are what make re-adoption PID-reuse-safe and config-exact."""
+``args`` are what make re-adoption PID-reuse-safe and config-exact.
+The file is owner-only because it holds the serve's API key."""
from __future__ import annotations
import json
import os
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, field
class AlreadyRunning(RuntimeError):
@@ -63,6 +64,7 @@ class ServeState:
args: list[str]
starttime: int | None = None
log_path: str | None = None
+ api_key: str | None = field(default=None, repr=False)
class ServeStateStore:
@@ -72,7 +74,12 @@ class ServeStateStore:
def save(self, state: ServeState) -> None:
os.makedirs(os.path.dirname(self.path) or ".", exist_ok=True)
tmp = f"{self.path}.tmp"
- with open(tmp, "w") as fh:
+ # unlink first: O_CREAT applies the 0o600 mode only to a file it creates
+ try:
+ os.remove(tmp)
+ except FileNotFoundError:
+ pass
+ with os.fdopen(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), "w") as fh:
json.dump(asdict(state), fh)
fh.flush()
os.fsync(fh.fileno())
@@ -102,6 +109,7 @@ class ServeStateStore:
args=list(doc.get("args") or []),
starttime=doc.get("starttime"),
log_path=doc.get("log_path"),
+ api_key=doc.get("api_key"),
)
except (KeyError, TypeError, ValueError):
return None
diff --git a/python/freetoken/daemon/proxy.py b/python/freetoken/daemon/proxy.py
index 9e382a4d..c4f0ba28 100644
--- a/python/freetoken/daemon/proxy.py
+++ b/python/freetoken/daemon/proxy.py
@@ -49,6 +49,7 @@ class ServeProbe:
now: Callable[[], float] = time.monotonic,
opener: Callable[[str, float], dict] | None = None,
prepare_opener: Callable[[str, float], dict] | None = None,
+ api_key: Callable[[], str | None] = lambda: None,
) -> None:
self._host = host
self._ttl = ttl_s
@@ -57,6 +58,7 @@ class ServeProbe:
self._now = now
self._opener = opener or self._urlopen
self._prepare_opener = prepare_opener or self._urlopen_prepare
+ self._api_key = api_key
self._lock = threading.Lock()
self._cache: dict[tuple[str, int], tuple[float, dict]] = {}
@@ -109,19 +111,23 @@ class ServeProbe:
result["reachable"] = True
return result
- @staticmethod
- def _urlopen(url: str, timeout: float) -> dict:
- req = urllib.request.Request(url, headers={"Accept": "application/json"}, method="GET")
+ def _headers(self) -> dict[str, str]:
+ headers = {"Accept": "application/json"}
+ if key := self._api_key():
+ headers["Authorization"] = f"Bearer {key}"
+ return headers
+
+ def _urlopen(self, url: str, timeout: float) -> dict:
+ req = urllib.request.Request(url, headers=self._headers(), method="GET")
with urllib.request.urlopen(req, timeout=timeout) as resp:
raw = resp.read()
return json.loads(raw.decode("utf-8"))
- @staticmethod
- def _urlopen_prepare(url: str, timeout: float) -> dict:
+ def _urlopen_prepare(self, url: str, timeout: float) -> dict:
req = urllib.request.Request(
url,
data=b"{}",
- headers={"Accept": "application/json", "Content-Type": "application/json"},
+ headers={**self._headers(), "Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(req, timeout=timeout) as resp:
diff --git a/python/freetoken/daemon/serve_manager.py b/python/freetoken/daemon/serve_manager.py
index 681bdef4..9d5e51fe 100644
--- a/python/freetoken/daemon/serve_manager.py
+++ b/python/freetoken/daemon/serve_manager.py
@@ -26,6 +26,8 @@ import time
from dataclasses import dataclass
from typing import Any, Callable
+from freetoken.launch import API_KEY_ENV
+
from . import osproc
from .accounting import (
AccountingOutbox,
@@ -37,7 +39,7 @@ from .accounting import (
class Conflict(RuntimeError):
- """A different serve (model/port/args) is already running; the client should switch()."""
+ """A different serve (model/port/args/key) is already running; the client should switch()."""
@dataclass
@@ -128,7 +130,14 @@ def build_serve_command(
return argv, log_path
-def spawn_serve(argv: list[str], log_path: str) -> PopenChild:
+def serve_env(api_key: str | None) -> dict[str, str]:
+ env = {k: v for k, v in os.environ.items() if k != API_KEY_ENV}
+ if api_key:
+ env[API_KEY_ENV] = api_key
+ return env
+
+
+def spawn_serve(argv: list[str], log_path: str, api_key: str | None = None) -> PopenChild:
"""Spawn the serve as a session leader with its stdout+stderr going to a real logfile fd (never
a PIPE): the file survives daemon death, so a re-adopting daemon just resumes tailing it and
the serve never writes to a dead pipe. ``start_new_session`` makes it a process
@@ -138,6 +147,7 @@ def spawn_serve(argv: list[str], log_path: str) -> PopenChild:
try:
proc = subprocess.Popen(
argv,
+ env=serve_env(api_key),
stdout=logf,
stderr=subprocess.STDOUT,
stdin=subprocess.DEVNULL,
@@ -158,7 +168,7 @@ class ServeManager:
ring,
state_store,
*,
- spawn_fn: Callable[[str, int, list[str]], object] | None = None,
+ spawn_fn: Callable[[str, int, list[str], str | None], object] | None = None,
adopt_fn: Callable[[object], object] | None = None,
tailer_factory: Callable[[object], object] | None = None,
signal_fn: Callable[[int, int], None] | None = None,
@@ -217,6 +227,7 @@ class ServeManager:
self._model: str | None = None
self._port: int | None = None
self._args: list[str] = []
+ self._api_key: str | None = None
self._started_at: float | None = None
self._last_exit: ExitInfo | None = None
self._adopted = False
@@ -232,11 +243,11 @@ class ServeManager:
# ---- default factories (overridable for tests) ----
- def _default_spawn(self, model: str, port: int, args: list[str]):
+ def _default_spawn(self, model: str, port: int, args: list[str], api_key: str | None):
argv, log_path = build_serve_command(
model, port, args, python=self._python, log_dir=self._log_dir
)
- return spawn_serve(argv, log_path)
+ return spawn_serve(argv, log_path, api_key)
def _default_adopt(self, state):
if not osproc.is_ft_serve_on_port(state.pid, state.port, starttime=state.starttime):
@@ -256,13 +267,25 @@ class ServeManager:
# ---- lifecycle ----
def start(
- self, model: str, port: int, args: list[str] | None = None, *, _auto: bool = False
+ self,
+ model: str,
+ port: int,
+ args: list[str] | None = None,
+ api_key: str | None = None,
+ *,
+ _auto: bool = False,
) -> dict:
with self._lifecycle:
- return self._start(model, port, args, _auto=_auto)
+ return self._start(model, port, args, api_key, _auto=_auto)
def _start(
- self, model: str, port: int, args: list[str] | None = None, *, _auto: bool = False
+ self,
+ model: str,
+ port: int,
+ args: list[str] | None = None,
+ api_key: str | None = None,
+ *,
+ _auto: bool = False,
) -> dict:
args = list(args or [])
with self._cond:
@@ -278,10 +301,13 @@ class ServeManager:
self._stop_requested = False # an explicit client start clears a prior stop intent
while True:
if self._child is not None and not self._stopping:
- if (self._model, self._port, self._args) == (model, port, args):
+ if (self._model, self._port, self._args, self._api_key) == (
+ model, port, args, api_key
+ ):
return {"pid": self._child.pid, "idempotent": True}
raise Conflict(
- f"serve already running (model={self._model!r} port={self._port}); "
+ f"serve already running with a different config "
+ f"(model={self._model!r} port={self._port}); "
f"use switch to replace it"
)
if self._starting:
@@ -299,7 +325,7 @@ class ServeManager:
child = None
try:
- child = self._spawn_fn(model, port, args)
+ child = self._spawn_fn(model, port, args, api_key)
finally:
if child is None:
with self._cond:
@@ -311,6 +337,7 @@ class ServeManager:
self._model = model
self._port = port
self._args = args
+ self._api_key = api_key
self._started_at = self._now()
self._last_exit = None
self._adopted = getattr(child, "adopted", False)
@@ -318,7 +345,7 @@ class ServeManager:
self._starting = False
self._cond.notify_all()
- self._persist(child, model, port, args)
+ self._persist(child, model, port, args, api_key)
self._maybe_apply_oom(child.pid)
self._begin_watch(child)
self._emit(f"serve started (pid={child.pid} model={model} port={port})")
@@ -407,10 +434,11 @@ class ServeManager:
port: int,
args: list[str] | None = None,
force: bool = False,
+ api_key: str | None = None,
) -> dict:
with self._lifecycle:
stopped = self._stop(force=force)
- started = self._start(model, port, args)
+ started = self._start(model, port, args, api_key)
return {**started, "accounting": stopped["accounting"]}
def pending_accounting(self) -> list[dict[str, Any]]:
@@ -734,6 +762,7 @@ class ServeManager:
self._model = state.model
self._port = state.port
self._args = list(state.args)
+ self._api_key = state.api_key
self._started_at = self._now() # unknown true start; report uptime since adoption
self._last_exit = None
self._adopted = True
@@ -824,13 +853,13 @@ class ServeManager:
return f"serve exited with code {info.code} (pid={child.pid})"
def _restart_async(self, dead_child) -> None:
- model, port, args = self._model, self._port, list(self._args)
+ model, port, args, api_key = self._model, self._port, list(self._args), self._api_key
if model is None or port is None:
return
def _run():
try:
- self.start(model, port, args, _auto=True)
+ self.start(model, port, args, api_key, _auto=True)
except Exception as exc: # noqa: BLE001
self._emit(f"auto-restart failed: {exc}")
@@ -867,6 +896,10 @@ class ServeManager:
with self._cond:
return list(self._args)
+ def serve_api_key(self) -> str | None:
+ with self._cond:
+ return self._api_key
+
def status(self) -> dict:
with self._cond:
child = self._child
@@ -892,7 +925,9 @@ class ServeManager:
# ---- helpers ----
- def _persist(self, child, model: str, port: int, args: list[str]) -> None:
+ def _persist(
+ self, child, model: str, port: int, args: list[str], api_key: str | None
+ ) -> None:
from .pidfile import ServeState
self._store.save(
@@ -903,6 +938,7 @@ class ServeManager:
args=list(args),
starttime=getattr(child, "starttime", None),
log_path=getattr(child, "log_path", None),
+ api_key=api_key,
)
)
diff --git a/python/freetoken/daemon/server.py b/python/freetoken/daemon/server.py
index d4e742b0..76e7e789 100644
--- a/python/freetoken/daemon/server.py
+++ b/python/freetoken/daemon/server.py
@@ -132,7 +132,8 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft daemon") -> int:
ring = LogRing(capacity=args.log_capacity)
store = ServeStateStore(os.path.join(state_dir, "serve.json"))
- probe = ServeProbe()
+ # read at call time: the running serve's key, from the manager created below
+ probe = ServeProbe(api_key=lambda: manager.serve_api_key())
def tailer_factory(child):
log_path = getattr(child, "log_path", None)
diff --git a/python/freetoken/launch.py b/python/freetoken/launch.py
index 5aac9389..e3c42154 100644
--- a/python/freetoken/launch.py
+++ b/python/freetoken/launch.py
@@ -5,6 +5,7 @@ import json
import os
import shlex
import shutil
+import stat
import subprocess
import sys
import time
@@ -20,7 +21,7 @@ DEFAULT_SERVER = "http://127.0.0.1:1919"
CODEX_PROFILE = "freetoken-launch"
CODEX_PROVIDER_NAME = "FreeToken"
CODEX_CATALOG_NAME = "freetoken-model.json"
-CODEX_PROVIDER_API_KEY_ENV = "FREETOKEN_API_KEY"
+API_KEY_ENV = "FREETOKEN_API_KEY"
# Used when the server reports no context length. Guessing low only costs earlier compaction.
FALLBACK_CONTEXT_WINDOW = 128_000
MAX_OUTPUT_TOKENS_CAP = 32_768
@@ -71,6 +72,7 @@ class LaunchContext:
extra_args: list[str]
dry_run: bool
assume_yes: bool = False
+ api_key: str | None = None
@dataclass(frozen=True)
@@ -167,9 +169,15 @@ def resolve_server_url(server: str | None) -> ServerURL:
return ServerURL(origin=origin, openai_base_url=f"{origin}/v1")
-def _get_json(url: str) -> object:
- request = Request(url, headers={"Accept": "application/json"})
- with urlopen(request, timeout=5) as response:
+def resolve_api_key(api_key: str | None) -> str | None:
+ return api_key or os.environ.get(API_KEY_ENV) or None
+
+
+def _get_json(url: str, api_key: str | None) -> object:
+ headers = {"Accept": "application/json"}
+ if api_key:
+ headers["Authorization"] = f"Bearer {api_key}"
+ with urlopen(Request(url, headers=headers), timeout=5) as response:
return json.loads(response.read().decode("utf-8"))
@@ -177,10 +185,10 @@ def _positive_int(value: object) -> int | None:
return value if isinstance(value, int) and not isinstance(value, bool) and value > 0 else None
-def _stats_model(server: ServerURL) -> dict[str, object]:
+def _stats_model(server: ServerURL, api_key: str | None) -> dict[str, object]:
"""The /v1/stats model card; empty when the server predates it."""
try:
- payload = _get_json(f"{server.origin}/v1/stats")
+ payload = _get_json(f"{server.origin}/v1/stats", api_key)
except (HTTPError, URLError, HTTPException, OSError, TimeoutError, ValueError):
return {}
model = payload.get("model") if isinstance(payload, dict) else None
@@ -193,11 +201,16 @@ def _input_modalities(stats_model: dict[str, object]) -> tuple[str, ...]:
return ("text", *extra)
-def discover_server_model(server: ServerURL) -> ServedModel:
+def discover_server_model(server: ServerURL, api_key: str | None) -> ServedModel:
try:
- _get_json(server.openai_base_url)
- payload = _get_json(f"{server.openai_base_url}/models")
+ _get_json(server.openai_base_url, api_key)
+ payload = _get_json(f"{server.openai_base_url}/models", api_key)
except (HTTPError, URLError, HTTPException, OSError, TimeoutError) as exc:
+ if isinstance(exc, HTTPError) and exc.code == 401:
+ raise RuntimeError(
+ f"FreeToken server at {server.origin} needs a valid API key: "
+ f"pass --api-key or set {API_KEY_ENV}"
+ ) from exc
raise RuntimeError(f"Cannot connect to FreeToken server at {server.origin}: {exc}") from exc
if not isinstance(payload, dict):
@@ -220,7 +233,7 @@ def discover_server_model(server: ServerURL) -> ServedModel:
if not models:
raise RuntimeError(f"FreeToken server at {server.origin} reported no models")
- stats_model = _stats_model(server)
+ stats_model = _stats_model(server, api_key)
if context_length is None:
context_length = _positive_int(stats_model.get("ctx"))
@@ -236,15 +249,22 @@ def _backup_path(path: Path) -> Path:
return path.with_name(f"{path.name}.{time.time_ns()}.bak")
-def _write_text_with_backup(path: Path, text: str) -> None:
+def _write_text_with_backup(path: Path, text: str, *, private: bool = False) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
if path.exists() and path.read_text() != text:
- shutil.copy2(path, _backup_path(path))
+ backup = _backup_path(path)
+ # copy2 sets the mode only after it copies the content, so create the backup with the source mode first
+ backup.touch(mode=stat.S_IMODE(path.stat().st_mode))
+ shutil.copy2(path, backup)
+ if private:
+ # before the write, so the key never sits in a file others can read
+ path.touch(mode=0o600)
+ path.chmod(0o600)
path.write_text(text)
-def _write_json_with_backup(path: Path, value: object) -> None:
- _write_text_with_backup(path, json.dumps(value, indent=2) + "\n")
+def _write_json_with_backup(path: Path, value: object, *, private: bool = False) -> None:
+ _write_text_with_backup(path, json.dumps(value, indent=2) + "\n", private=private)
def _toml_string(value: str) -> str:
@@ -371,7 +391,7 @@ def _codex_profile_text(ctx: LaunchContext, catalog_path: Path) -> str:
+ f"name = {_toml_string(CODEX_PROVIDER_NAME)}\n"
+ f"base_url = {_toml_string(ctx.server.openai_base_url)}\n"
+ 'wire_api = "responses"\n'
- + f"env_key = {_toml_string(CODEX_PROVIDER_API_KEY_ENV)}\n"
+ + f"env_key = {_toml_string(API_KEY_ENV)}\n"
)
@@ -408,7 +428,7 @@ def prepare_codex(ctx: LaunchContext) -> CommandSpec:
]
return CommandSpec(
argv=argv,
- env={CODEX_PROVIDER_API_KEY_ENV: "freetoken"},
+ env={API_KEY_ENV: ctx.api_key or "freetoken"},
unset_env=CODEX_CLEAR_ENV,
)
@@ -423,7 +443,7 @@ def prepare_claude(ctx: LaunchContext) -> CommandSpec:
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": str(_max_output_tokens(ctx)),
"ANTHROPIC_BASE_URL": ctx.server.origin,
"ANTHROPIC_API_KEY": "",
- "ANTHROPIC_AUTH_TOKEN": "freetoken",
+ "ANTHROPIC_AUTH_TOKEN": ctx.api_key or "freetoken",
"ANTHROPIC_MODEL": model_id,
"ANTHROPIC_DEFAULT_OPUS_MODEL": model_id,
"ANTHROPIC_DEFAULT_SONNET_MODEL": model_id,
@@ -456,13 +476,16 @@ def _opencode_model_entries(
def _opencode_config(ctx: LaunchContext) -> str:
model_ids = _ordered_model_ids(ctx)
+ options = {"baseURL": ctx.server.openai_base_url}
+ if ctx.api_key:
+ options["apiKey"] = ctx.api_key
config = {
"$schema": "https://opencode.ai/config.json",
"provider": {
OPENCODE_PROVIDER: {
"npm": "@ai-sdk/openai-compatible",
"name": OPENCODE_PROVIDER_NAME,
- "options": {"baseURL": ctx.server.openai_base_url},
+ "options": options,
"models": _opencode_model_entries(
model_ids, _context_window(ctx), _max_output_tokens(ctx), _accepts_images(ctx)
),
@@ -614,7 +637,7 @@ def _patch_openclaw_config(
new_models.append(entry)
provider["baseUrl"] = ctx.server.openai_base_url
- provider["apiKey"] = "freetoken-local"
+ provider["apiKey"] = ctx.api_key or "freetoken-local"
provider["api"] = "openai-completions"
provider["models"] = new_models
providers[OPENCLAW_PROVIDER] = provider
@@ -661,7 +684,9 @@ def prepare_openclaw(ctx: LaunchContext) -> CommandSpec:
if not _openclaw_has_freetoken_provider(config):
if not ctx.assume_yes and not _confirm_openclaw_first_patch(ctx, config_path):
raise RuntimeError("OpenClaw config patch cancelled")
- _write_json_with_backup(config_path, _patch_openclaw_config(ctx, config))
+ _write_json_with_backup(
+ config_path, _patch_openclaw_config(ctx, config), private=bool(ctx.api_key)
+ )
_clear_openclaw_session_overrides(ctx.model.model_id)
argv = ["openclaw", *ctx.extra_args] if ctx.extra_args else ["openclaw", "chat"]
@@ -697,8 +722,8 @@ def prepare_hermes(ctx: LaunchContext) -> CommandSpec:
model_section["default"] = ctx.model.model_id
model_section["provider"] = "custom"
model_section["base_url"] = ctx.server.openai_base_url
- # A non-empty dummy: FreeToken is unauthenticated, but some clients reject an empty key.
- model_section["api_key"] = HERMES_API_KEY
+ # Dummy for a server without --api-key; some clients reject an empty key.
+ model_section["api_key"] = ctx.api_key or HERMES_API_KEY
# Hermes' name for the window (prompt + generation). Left unset it auto-detects, and a
# miss lands on a 32k default that trips the floor below.
window = _context_window(ctx)
@@ -712,7 +737,9 @@ def prepare_hermes(ctx: LaunchContext) -> CommandSpec:
file=sys.stderr,
)
- _write_text_with_backup(config_path, yaml.safe_dump(config, sort_keys=False))
+ _write_text_with_backup(
+ config_path, yaml.safe_dump(config, sort_keys=False), private=bool(ctx.api_key)
+ )
argv = ["hermes", *ctx.extra_args] if ctx.extra_args else ["hermes", "chat"]
return CommandSpec(argv=argv, env={})
@@ -753,8 +780,7 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:
``reasoning_content``, while llm-pi-ai's JSON round-trip can change argument
values and key order — drift that survives render canonicalization, cuts
the prefix cache, and shows the model a rewrite of its own output. The
- dummy DEEPSEEK_API_KEY satisfies dsh's non-empty key requirement; FreeToken
- itself is unauthenticated."""
+ dummy DEEPSEEK_API_KEY satisfies dsh's non-empty key requirement."""
settings_path = _dsh_home() / DSH_LAUNCH_SETTINGS_NAME
patch_path = _dsh_home() / DSH_LAUNCH_PATCH_NAME
if not ctx.dry_run:
@@ -774,7 +800,7 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:
window, output = _context_window(ctx), _max_output_tokens(ctx)
modalities = ["text", "image"] if _accepts_images(ctx) else ["text"]
- config["llm-deepseek"] = {
+ section: dict[str, object] = {
"baseURL": ctx.server.openai_base_url,
"models": [
{
@@ -787,6 +813,10 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:
for model_id in _ordered_model_ids(ctx)
],
}
+ if ctx.api_key:
+ # not DEEPSEEK_API_KEY: dsh's web search also reads it and sends it to api.deepseek.com
+ section["apiKeyEnv"] = API_KEY_ENV
+ config["llm-deepseek"] = section
config["agent-default-model"] = {
"provider": "deepseek-official",
"model": ctx.model.model_id,
@@ -804,15 +834,14 @@ def prepare_dsh(ctx: LaunchContext) -> CommandSpec:
elif len(app_args) >= 2 and app_args[0] == "--profile":
profile, app_args = app_args[1], app_args[2:]
argv = ["dsh", "--profile", profile, "--patch", str(patch_path), *app_args]
- return CommandSpec(
- argv=argv,
- env={
- "DEEPSEEK_BASE_URL": ctx.server.openai_base_url,
- "DEEPSEEK_API_KEY": DSH_API_KEY,
- "DSH_TELEMETRY_DISABLED": "1",
- },
- unset_env=CLOUD_PROVIDER_API_KEY_ENV,
- )
+ env = {
+ "DEEPSEEK_BASE_URL": ctx.server.openai_base_url,
+ "DEEPSEEK_API_KEY": DSH_API_KEY,
+ "DSH_TELEMETRY_DISABLED": "1",
+ }
+ if ctx.api_key:
+ env[API_KEY_ENV] = ctx.api_key
+ return CommandSpec(argv=argv, env=env, unset_env=CLOUD_PROVIDER_API_KEY_ENV)
PREPARERS = {
@@ -840,6 +869,10 @@ def parse_argv(argv: list[str], prog: str = "python -m freetoken.launch") -> arg
)
parser.add_argument("agent", choices=sorted(PREPARERS))
parser.add_argument("--server", help="FreeToken server origin or /v1 URL")
+ parser.add_argument(
+ "--api-key",
+ help=f"API key of a server started with --api-key (default: ${API_KEY_ENV})",
+ )
parser.add_argument(
"--dry-run",
action="store_true",
@@ -1028,13 +1061,16 @@ def main(argv: list[str] | None = None, prog: str = "python -m freetoken.launch"
return 0
server = resolve_server_url(args.server)
- model = discover_server_model(server)
+ api_key = resolve_api_key(args.api_key)
+ model = discover_server_model(server, api_key)
plan_ctx = LaunchContext(
server=server,
model=model,
extra_args=args.extra_args,
dry_run=True,
assume_yes=args.yes,
+ # the plan is printed by --dry-run, so it never holds the real key
+ api_key="<api-key>" if api_key else None,
)
spec = PREPARERS[args.agent](plan_ctx)
if args.dry_run:
@@ -1052,6 +1088,7 @@ def main(argv: list[str] | None = None, prog: str = "python -m freetoken.launch"
extra_args=args.extra_args,
dry_run=False,
assume_yes=args.yes,
+ api_key=api_key,
)
spec = PREPARERS[args.agent](ctx)
if binary_path != spec.argv[0]:
diff --git a/python/freetoken/server/api_server.py b/python/freetoken/server/api_server.py
index 34221cfc..a9b16adf 100644
--- a/python/freetoken/server/api_server.py
+++ b/python/freetoken/server/api_server.py
@@ -2,6 +2,8 @@ from __future__ import annotations
import asyncio
import contextlib
+import hashlib
+import hmac
import json
import os
import signal
@@ -34,6 +36,7 @@ from freetoken.utils import (
load_generation_sampling,
)
from pydantic import BaseModel
+from starlette.datastructures import Headers
from .args import ServerArgs
from .anthropic_api import register_anthropic_routes
@@ -417,6 +420,39 @@ def install_cors(app: FastAPI, origins_csv: str) -> None:
)
+class _ApiKeyMiddleware:
+ def __init__(self, app, api_key: str) -> None:
+ self.app = app
+ self._digest = hashlib.sha256(api_key.encode()).digest()
+
+ def _matches(self, value: str | None) -> bool:
+ # compare digests so the time taken does not depend on the key length
+ return value is not None and hmac.compare_digest(
+ hashlib.sha256(value.encode()).digest(), self._digest
+ )
+
+ async def __call__(self, scope, receive, send) -> None:
+ if scope["type"] not in ("http", "websocket") or scope["path"] == "/health":
+ return await self.app(scope, receive, send)
+ headers = Headers(scope=scope)
+ scheme, _, token = headers.get("authorization", "").partition(" ")
+ if (scheme.lower() == "bearer" and self._matches(token)) or self._matches(
+ headers.get("x-api-key")
+ ):
+ return await self.app(scope, receive, send)
+ await JSONResponse({"error": "Unauthorized"}, status_code=401)(scope, receive, send)
+
+
+def install_api_key(app: FastAPI, api_key: str | None) -> None:
+ """Require ``api_key`` on every route but /health.
+
+ Run it before install_cors, so CORS answers preflights and adds its headers to 401s."""
+ if api_key is None:
+ return
+ app.add_middleware(_ApiKeyMiddleware, api_key=api_key)
+ logger.info("API key required on every route except /health")
+
+
app = FastAPI(title="FreeToken API Server", version=__version__, lifespan=lifespan)
register_openai_routes(app, get_global_state, lambda: _MODEL_SAMPLING)
register_anthropic_routes(app, get_global_state, lambda: _MODEL_SAMPLING)
@@ -883,7 +919,7 @@ def _install_shell_stop_handlers() -> None:
signal.signal(sig, _flag_shutdown)
-def _serve_and_run_shell(host: str, port: int) -> None:
+def _serve_and_run_shell(host: str, port: int, api_key: str | None) -> None:
"""Shell mode: serve the API here, and attach the terminal client to it over the loopback.
The shell is an ordinary API client (see ``freetoken.shell``), so shell mode is just
@@ -916,7 +952,7 @@ def _serve_and_run_shell(host: str, port: int) -> None:
# /health and echoes the same load progress the desktop app polls for. A ^C during that
# wait is a stop, not a crash -- exit through the teardown below, not a traceback.
with contextlib.suppress(KeyboardInterrupt):
- asyncio.run(run_shell(origin, connect_grace=30.0))
+ asyncio.run(run_shell(origin, connect_grace=30.0, api_key=api_key))
finally:
server.should_exit = True
thread.join(timeout=15)
@@ -958,6 +994,7 @@ def run_api_server(config: ServerArgs, start_backend: Callable[[], "Any"], run_s
host = config.server_host
port = config.server_port
+ install_api_key(app, config.api_key)
# Create/validate FREETOKEN_API_LOG_DIR and start the writer thread up front, so a
# bad path is reported at boot rather than silently on the first request.
install_cors(app, config.cors_origins)
@@ -1044,7 +1081,7 @@ def run_api_server(config: ServerArgs, start_backend: Callable[[], "Any"], run_s
).start()
if run_shell:
- _serve_and_run_shell(host, port)
+ _serve_and_run_shell(host, port, config.api_key)
return
# uvicorn stays on the main thread (signal handling unchanged); ^C reaches the worker group.
uvicorn.run(app, host=host, port=port)
diff --git a/python/freetoken/server/args.py b/python/freetoken/server/args.py
index b8d06018..5e6caa75 100644
--- a/python/freetoken/server/args.py
+++ b/python/freetoken/server/args.py
@@ -3,7 +3,7 @@ from __future__ import annotations
import argparse
import json
import os
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from typing import List, Tuple
import torch
@@ -38,6 +38,8 @@ def _nvfp4_entry(value: str) -> str:
class ServerArgs(SchedulerConfig):
server_host: str = "127.0.0.1"
server_port: int = 1919
+ # kept out of repr: parse_args logs the whole ServerArgs
+ api_key: str | None = field(default=None, repr=False)
num_tokenizer: int = 0
silent_output: bool = False
# The terminal shell is attached to this server (ft shell --model / ft serve --shell-mode).
@@ -368,6 +370,15 @@ def parse_args(
help="The port number for the server to listen on.",
)
+ parser.add_argument(
+ "--api-key",
+ type=str,
+ default=ServerArgs.api_key,
+ help="Require this key on every route except /health, sent as "
+ "'Authorization: Bearer <key>' or 'x-api-key: <key>'. Defaults to $FREETOKEN_API_KEY; "
+ "unset serves without authentication.",
+ )
+
parser.add_argument(
"--cuda-graph-max-bs",
"--graph",
@@ -842,6 +853,13 @@ def parse_args(
if entry:
kwargs["quant_backend"] = entry
+ # an empty flag usually means an unset shell variable; refuse it rather than serve open
+ if kwargs["api_key"] == "":
+ parser.error("--api-key is empty; omit it to serve without authentication")
+ from freetoken.launch import resolve_api_key
+
+ kwargs["api_key"] = resolve_api_key(kwargs["api_key"])
+
if kwargs["model_path"].startswith("~"):
kwargs["model_path"] = os.path.expanduser(kwargs["model_path"])
diff --git a/python/freetoken/shell/__init__.py b/python/freetoken/shell/__init__.py
index e429f487..d31eed4c 100644
--- a/python/freetoken/shell/__init__.py
+++ b/python/freetoken/shell/__init__.py
@@ -45,6 +45,10 @@ def _build_parser(prog: str) -> argparse.ArgumentParser:
default=None,
help="FreeToken server URL (default: $FREETOKEN_HOST, else http://127.0.0.1:1919)",
)
+ parser.add_argument(
+ "--api-key",
+ help="API key of a server started with --api-key (default: $FREETOKEN_API_KEY)",
+ )
return parser
@@ -63,7 +67,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft shell") -> int:
except SystemExit as exc:
return int(exc.code) if isinstance(exc.code, int) else 2
- from freetoken.launch import resolve_server_url
+ from freetoken.launch import resolve_api_key, resolve_server_url
try:
server = resolve_server_url(parsed.server)
@@ -74,7 +78,7 @@ def main(argv: Sequence[str] | None = None, *, prog: str = "ft shell") -> int:
from .tui import run_shell
try:
- return asyncio.run(run_shell(server.origin))
+ return asyncio.run(run_shell(server.origin, api_key=resolve_api_key(parsed.api_key)))
except KeyboardInterrupt:
return 130
diff --git a/python/freetoken/shell/client.py b/python/freetoken/shell/client.py
index 183fa4df..d1115362 100644
--- a/python/freetoken/shell/client.py
+++ b/python/freetoken/shell/client.py
@@ -27,7 +27,7 @@ from typing import Any
import openai
from openai import AsyncOpenAI
-# Any string is accepted by the server; sent so the SDK doesn't refuse to build a request.
+# Sent when no key is given: a server without --api-key accepts any string, and the SDK needs one.
LOCAL_API_KEY = "freetoken-local"
CONTROL_TIMEOUT = 10.0
# Per-read timeout on the chat stream. Generous: it has to cover the gap before the first
@@ -97,14 +97,15 @@ class ShellClient:
self,
origin: str,
*,
- api_key: str = LOCAL_API_KEY,
+ api_key: str | None = None,
timeout: float = CONTROL_TIMEOUT,
) -> None:
self.origin = origin.rstrip("/")
self.timeout = timeout
+ self._api_key = api_key or LOCAL_API_KEY
self._openai = AsyncOpenAI(
base_url=f"{self.origin}/v1",
- api_key=api_key,
+ api_key=self._api_key,
max_retries=0, # a retried chat request would generate the turn twice
timeout=openai.Timeout(CHAT_READ_TIMEOUT, connect=10.0),
)
@@ -118,7 +119,7 @@ class ShellClient:
self, method: str, path: str, body: dict[str, Any] | None, timeout: float
) -> dict[str, Any]:
data = None
- headers = {"Accept": "application/json"}
+ headers = {"Accept": "application/json", "Authorization": f"Bearer {self._api_key}"}
if body is not None:
data = json.dumps(body).encode("utf-8")
headers["Content-Type"] = "application/json"
diff --git a/python/freetoken/shell/tui.py b/python/freetoken/shell/tui.py
index 93bd18cc..72d7ebe0 100644
--- a/python/freetoken/shell/tui.py
+++ b/python/freetoken/shell/tui.py
@@ -515,13 +515,15 @@ def _format_load_progress(doc: dict) -> str:
return f"loading ({phase})..."
-async def run_shell(origin: str, *, connect_grace: float = 0.0) -> int:
+async def run_shell(
+ origin: str, *, connect_grace: float = 0.0, api_key: str | None = None
+) -> int:
"""Attach to the FreeToken server at ``origin`` and run the terminal chat.
``connect_grace`` is how long to keep retrying a refused connection before giving up --
left at 0 when attaching to a server the user says is already running, raised when the
caller just started one in this process (see ``server/api_server.py``)."""
- client = ShellClient(origin)
+ client = ShellClient(origin, api_key=api_key)
try:
return await _run_shell(client, origin, connect_grace=connect_grace)
finally:
diff --git a/tests/daemon/test_daemon_serve_manager.py b/tests/daemon/test_daemon_serve_manager.py
index fd9956eb..cfd84ae6 100644
--- a/tests/daemon/test_daemon_serve_manager.py
+++ b/tests/daemon/test_daemon_serve_manager.py
@@ -1,19 +1,25 @@
from __future__ import annotations
+import os
import signal
+import sys
import threading
import time
+from concurrent.futures import ThreadPoolExecutor
import pytest
+from fastapi.testclient import TestClient
+from freetoken.daemon import proxy
from freetoken.daemon.accounting import (
AccountingOutbox,
AccountingOutboxError,
AccountingPrepareError,
)
+from freetoken.daemon.app import build_app
from freetoken.daemon.logring import LogRing
from freetoken.daemon.pidfile import ServeState, ServeStateStore
-from freetoken.daemon.serve_manager import Conflict, ExitInfo, ServeManager
+from freetoken.daemon.serve_manager import Conflict, ExitInfo, ServeManager, spawn_serve
# --------------------------------------------------------------------------- test doubles
@@ -50,11 +56,13 @@ class Spawner:
def __init__(self):
self.children: list[FakeChild] = []
self.calls: list[tuple] = []
+ self.api_keys: list[str | None] = []
self._pid = 1000
self.gate: threading.Event | None = None
- def __call__(self, model, port, args) -> FakeChild:
+ def __call__(self, model, port, args, api_key=None) -> FakeChild:
self.calls.append((model, port, list(args)))
+ self.api_keys.append(api_key)
if self.gate is not None:
self.gate.wait()
self._pid += 1
@@ -743,6 +751,131 @@ def test_readopt_no_state_is_noop(tmp_path):
assert mgr.readopt() is False
+# --------------------------------------------------------------------------- API key
+
+
+def test_api_key_is_serve_config_kept_owner_only_and_readopted(tmp_path):
+ sp = Spawner()
+ mgr, store, _ = make_manager(tmp_path, sp)
+ # an older daemon left a world-readable state file and a stale tmp behind
+ for path in (store.path, f"{store.path}.tmp"):
+ with open(path, "w") as fh:
+ fh.write("{}")
+ os.chmod(path, 0o644)
+ mgr.start("m", 1919, [], "k1")
+ assert sp.api_keys == ["k1"] and mgr.serve_api_key() == "k1"
+ assert mgr.start("m", 1919, [], "k1")["idempotent"] is True
+ with pytest.raises(Conflict):
+ mgr.start("m", 1919, [], "k2")
+ assert store.load().api_key == "k1"
+ assert os.stat(store.path).st_mode & 0o777 == 0o600
+
+ adopted = FakeChild(4242, adopted=True)
+ fresh = ServeManager(
+ LogRing(), store, spawn_fn=Spawner(), adopt_fn=lambda state: adopted, tailer_factory=None,
+ signal_fn=lambda p, s: None, apply_oom=False,
+ )
+ assert fresh.readopt() is True and fresh.serve_api_key() == "k1"
+ adopted.die()
+ sp.children[0].die()
+
+
+def test_switch_replaces_the_api_key(tmp_path):
+ sp = Spawner()
+
+ def sig(pid, s):
+ if s == signal.SIGTERM:
+ sp.by_pid(pid).die(0)
+
+ mgr, store, _ = make_manager(tmp_path, sp, signal_fn=sig)
+ mgr.start("m", 1919, [], "k1")
+ mgr.switch("m", 1919, [], False, "k2")
+ assert sp.api_keys == ["k1", "k2"]
+ assert mgr.serve_api_key() == "k2" and store.load().api_key == "k2"
+ sp.children[1].die()
+
+
+def test_auto_restart_keeps_the_api_key(tmp_path):
+ sp = Spawner()
+ mgr, _, _ = make_manager(tmp_path, sp, auto_restart=True)
+ mgr.start("m", 1919, [], "k1")
+ sp.children[0].die(1)
+ assert wait_until(lambda: len(sp.children) == 2)
+ assert sp.api_keys == ["k1", "k1"]
+ sp.children[1].die()
+
+
+def test_spawned_serve_sees_only_the_requested_key(tmp_path, monkeypatch):
+ monkeypatch.setenv("FREETOKEN_API_KEY", "from-daemon-env")
+ code = "import os; print(os.environ.get('FREETOKEN_API_KEY'))"
+ for api_key in (None, "k1"):
+ log = tmp_path / f"{api_key}.log"
+ child = spawn_serve([sys.executable, "-c", code], str(log), api_key)
+ child.wait()
+ child.close()
+ assert log.read_text().strip() == str(api_key)
+
+
+def test_probe_sends_the_running_serves_key(monkeypatch):
+ seen = []
+
+ class Response:
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc):
+ return False
+
+ def read(self):
+ return b"{}"
+
+ def fake_urlopen(req, timeout):
+ seen.append(req.get_header("Authorization"))
+ return Response()
+
+ monkeypatch.setattr(proxy.urllib.request, "urlopen", fake_urlopen)
+ key = None
+ probe = proxy.ServeProbe(api_key=lambda: key)
+ probe.fresh_stats(1919)
+ key = "k1"
+ probe.fresh_stats(1919)
+ probe.prepare_stop(1919)
+ assert seen == [None, "Bearer k1", "Bearer k1"]
+
+
+def test_start_and_switch_routes_hand_the_api_key_to_the_manager():
+ calls = []
+
+ class Manager:
+ def status(self):
+ return {"running": False}
+
+ def start(self, *args):
+ calls.append(args)
+ return {"pid": 1, "idempotent": False}
+
+ def switch(self, *args):
+ calls.append(args)
+ return {"pid": 1, "idempotent": False, "accounting": None}
+
+ with ThreadPoolExecutor(1) as lifecycle_pool, ThreadPoolExecutor(1) as proxy_pool:
+ app = build_app(
+ manager=Manager(), ring=LogRing(), probe=None, footprint_fn=lambda pid: {},
+ lifecycle_pool=lifecycle_pool, proxy_pool=proxy_pool,
+ )
+ with TestClient(app) as client:
+ client.post("/engine/start", json={"model": "m", "port": 1919, "apiKey": "k1"})
+ client.post("/engine/start", json={"model": "m", "port": 1919, "apiKey": ""})
+ client.post("/engine/start", json={"model": "m", "port": 1919})
+ client.post("/engine/switch", json={"model": "m", "port": 1919, "apiKey": "k2"})
+ for args in (["--api-key", "k3"], ["--api-key=k3"], ["--api", "k3"], ["--ap=k3"]):
+ rejected = client.post("/engine/start", json={"model": "m", "args": args})
+ assert rejected.status_code == 400
+ allowed = client.post("/engine/start", json={"model": "m", "args": ["--attn", "fa"]})
+ assert allowed.status_code == 200
+ assert [args[-1] for args in calls] == ["k1", None, None, "k2", None]
+
+
# --------------------------------------------------------------------------- resource leak (L2)
diff --git a/tests/server/test_api_key.py b/tests/server/test_api_key.py
new file mode 100644
index 00000000..a655c688
--- /dev/null
+++ b/tests/server/test_api_key.py
@@ -0,0 +1,146 @@
+"""--api-key: the gate in front of every route but /health, and where the key comes from."""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+import yaml
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from freetoken import launch
+from freetoken.server.api_server import install_api_key, install_cors
+from freetoken.server.args import parse_args
+
+KEY = "sk-test"
+ORIGIN = "http://localhost:1420"
+
+
+def _client(api_key: str | None) -> TestClient:
+ app = FastAPI()
+ app.get("/health")(lambda: {"status": "ok"})
+ app.get("/v1/models")(lambda: {"data": []})
+ install_api_key(app, api_key)
+ install_cors(app, ORIGIN)
+ return TestClient(app)
+
+
+def _parse(*argv: str):
+ hf = SimpleNamespace(to_dict=lambda: {"architectures": ["Qwen3ForCausalLM"], "torch_dtype": "bfloat16"})
+ with patch("freetoken.utils.cached_load_hf_config", lambda _path: hf):
+ return parse_args(["--model", "/models/anon", *argv])[0]
+
+
+ "headers, status",
+ [
+ ({}, 401),
+ ({"Authorization": "Bearer wrong"}, 401),
+ ({"Authorization": f"Basic {KEY}"}, 401),
+ ({"Authorization": KEY}, 401),
+ ({"Authorization": b"Bearer caf\xe9"}, 401),
+ ({"x-api-key": "wrong"}, 401),
+ ({"Authorization": f"Bearer {KEY}"}, 200),
+ ({"Authorization": f"bearer {KEY}"}, 200),
+ ({"x-api-key": KEY}, 200),
+ ],
+)
+def test_key_gates_every_route_but_health(headers, status):
+ client = _client(KEY)
+ response = client.get("/v1/models", headers=headers)
+ assert response.status_code == status
+ if status == 401:
+ assert response.json() == {"error": "Unauthorized"}
+ assert client.get("/health").status_code == 200
+
+
+def test_no_key_serves_open():
+ assert _client(None).get("/v1/models").status_code == 200
+
+
+def test_cors_preflight_passes_and_401_carries_cors_headers():
+ client = _client(KEY)
+ preflight = client.options(
+ "/v1/models",
+ headers={"Origin": ORIGIN, "Access-Control-Request-Method": "GET",
+ "Access-Control-Request-Headers": "authorization"},
+ )
+ assert preflight.status_code == 200
+ denied = client.get("/v1/models", headers={"Origin": ORIGIN})
+ assert denied.status_code == 401
+ assert denied.headers["access-control-allow-origin"] == ORIGIN
+
+
+def test_options_outside_a_cors_preflight_needs_the_key():
+ assert _client(KEY).options("/v1/models").status_code == 401
+
+
+def test_flag_wins_over_env_and_empty_values_do_not_enable_auth(monkeypatch):
+ monkeypatch.delenv("FREETOKEN_API_KEY", raising=False)
+ assert _parse().api_key is None
+ monkeypatch.setenv("FREETOKEN_API_KEY", "from-env")
+ assert _parse().api_key == "from-env"
+ assert _parse("--api-key", KEY).api_key == KEY
+ monkeypatch.setenv("FREETOKEN_API_KEY", "")
+ assert _parse().api_key is None
+ with pytest.raises(SystemExit):
+ _parse("--api-key", "")
+
+
+def test_key_stays_out_of_the_logged_config(monkeypatch):
+ monkeypatch.delenv("FREETOKEN_API_KEY", raising=False)
+ assert KEY not in str(_parse("--api-key", KEY))
+
+
[email protected]("agent", sorted(launch.PREPARERS))
+def test_dry_run_prints_a_placeholder_instead_of_the_key(agent, monkeypatch, capsys):
+ key = 'p"w\\d\xe9'
+ model = launch.ServedModel(model_id="m", models=["m"], context_length=8192)
+ monkeypatch.setattr(launch, "discover_server_model", lambda _server, _key: model)
+ assert launch.main([agent, "--dry-run", "--api-key", key]) == 0
+ out = capsys.readouterr().out
+ assert key not in out and json.dumps(key)[1:-1] not in out
+ if agent in ("claude", "codex", "dsh", "opencode"):
+ assert "<api-key>" in out
+
+
+def test_dsh_keeps_the_key_out_of_the_variable_its_web_search_reads(monkeypatch, tmp_path):
+ monkeypatch.setenv("DSH_HOME", str(tmp_path))
+ monkeypatch.setattr(launch, "_warn_dsh_node_version", lambda: None)
+ ctx = launch.LaunchContext(
+ server=launch.resolve_server_url("http://127.0.0.1:1919"),
+ model=launch.ServedModel(model_id="m", models=["m"], context_length=8192),
+ extra_args=[],
+ dry_run=False,
+ api_key=KEY,
+ )
+ env = launch.prepare_dsh(ctx).env
+ settings = yaml.safe_load((tmp_path / launch.DSH_LAUNCH_SETTINGS_NAME).read_text())
+ assert env["DEEPSEEK_API_KEY"] != KEY
+ assert env[settings["llm-deepseek"]["apiKeyEnv"]] == KEY
+
+
[email protected]("agent", ["hermes", "openclaw"])
+def test_config_files_holding_the_key_are_owner_only(agent, monkeypatch, tmp_path):
+ monkeypatch.setenv("HOME", str(tmp_path))
+ old_umask = os.umask(0o022)
+ try:
+ for key in ("sk-first", "sk-second"):
+ ctx = launch.LaunchContext(
+ server=launch.resolve_server_url("http://127.0.0.1:1919"),
+ model=launch.ServedModel(model_id="m", models=["m"], context_length=65536),
+ extra_args=[],
+ dry_run=False,
+ assume_yes=True,
+ api_key=key,
+ )
+ launch.PREPARERS[agent](ctx)
+ finally:
+ os.umask(old_umask)
+ written = [p for p in tmp_path.rglob("*") if p.is_file() and "sk-" in p.read_text()]
+ assert len(written) == 2
+ assert all(stat.S_IMODE(p.stat().st_mode) == 0o600 for p in written)