captchakraken 2.2.0__tar.gz → 2.3.0__tar.gz

{captchakraken-2.2.0 → captchakraken-2.3.0}/.gitignore

@@ -41,4 +41,7 @@ record_demos*.log
 run_full_record.out
 run_full_record.sh
 *_video_attempt_*.png
-captcha_videos/
+captcha_videos/
+# Personal VSCode workspace files (machine-specific; belong at a project
+# root, not in the tree). One strayed into python/tests/.
+*.code-workspace

captchakraken-2.3.0/LICENSE

@@ -0,0 +1,105 @@
+CaptchaKraken Source-Available License v1.0
+Copyright (c) 2026 JobHarvest / JWriter20. All rights reserved.
+
+This license governs use of the CaptchaKraken software in this repository and of
+the associated machine-learning model weights and LoRA adapters published by the
+copyright holder (collectively, the "Software"). By using the Software you agree
+to these terms. If you do not agree, do not use the Software.
+
+================================================================================
+1. GRANT
+================================================================================
+Subject to the restrictions below, you are granted a worldwide, royalty-free,
+non-exclusive license to use, copy, modify, and distribute the Software, and to
+incorporate it into your own products and services.
+
+================================================================================
+2. PERMITTED USES
+================================================================================
+You MAY use the Software for:
+
+  (a) Personal, non-commercial use, research, and education.
+
+  (b) Commercial use INSIDE a larger product or service that delivers
+      substantial value BEYOND captcha solving itself — that is, where captcha
+      solving is an internal, enabling component rather than the product.
+
+  Illustrative (non-exhaustive) examples of PERMITTED commercial use:
+      - Web scrapers and data-collection pipelines.
+      - Stealth / anti-detection browsers and browser automation frameworks
+        that use the Software as one internal capability.
+      - QA, testing, and accessibility tooling.
+      - Any application where the captcha solve is a means to an end the user
+        is actually paying for.
+
+================================================================================
+3. PROHIBITED USES
+================================================================================
+You MAY NOT, without a separate written commercial agreement from the copyright
+holder:
+
+  (a) Sell, resell, rent, or otherwise offer for a fee any captcha-SOLVING
+      service, product, or API whose primary value is solving captchas,
+      where that service is powered by the Software or its model outputs.
+
+  (b) Distribute "thin wrappers" around the Software whose primary purpose is
+      captcha solving — including but not limited to browser extensions,
+      hosted endpoints, SaaS products, or CLIs that simply expose the
+      Software's solving capability to end users.
+
+  (c) Expose, proxy, or relay the responses or outputs of the Software's LoRA
+      models (e.g. bounding boxes, tile selections, click plans) through a paid
+      or public API as a captcha-solving service.
+
+  In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
+
+================================================================================
+4. MODEL OUTPUTS
+================================================================================
+Outputs produced by the model weights/adapters are subject to Sections 2 and 3
+to the same extent as the Software itself. Reselling or API-relaying those
+outputs as a captcha-solving service is prohibited under Section 3(c).
+
+================================================================================
+5. REDISTRIBUTION
+================================================================================
+If you redistribute the Software (modified or not), you must retain this license
+and this notice, and you must not remove or alter the restrictions in Section 3.
+
+================================================================================
+6. TRADEMARKS
+================================================================================
+This license does not grant permission to use the trade names, trademarks, or
+product names of the copyright holder, except as required to describe the origin
+of the Software.
+
+================================================================================
+7. NO WARRANTY
+================================================================================
+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.
+
+================================================================================
+8. RESPONSIBLE USE
+================================================================================
+You are responsible for ensuring your use of the Software complies with all
+applicable laws, the terms of service of any site you interact with, and
+applicable anti-fraud and computer-access statutes. The copyright holder does
+not endorse using the Software to violate any third party's terms or rights.
+
+================================================================================
+9. COMMERCIAL LICENSING
+================================================================================
+For uses prohibited under Section 3 — including selling captcha-solving as a
+service — contact the copyright holder to discuss a separate commercial license.
+
+--------------------------------------------------------------------------------
+This text is a license, not legal advice. If the boundary between a permitted
+"value-add" product and a prohibited "thin wrapper" is unclear for your use
+case, ask by opening an issue or messaging the maintainer on GitHub:
+https://github.com/JWriter20/CaptchaKraken
+--------------------------------------------------------------------------------

captchakraken-2.3.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: captchakraken
+Version: 2.3.0
+Summary: Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM.
+Project-URL: Homepage, https://github.com/JWriter20/CaptchaKraken
+Project-URL: Issues, https://github.com/JWriter20/CaptchaKraken/issues
+Author: Jake Writer
+License: CaptchaKraken Source-Available License v1.0
+        Copyright (c) 2026 JobHarvest / JWriter20. All rights reserved.
+        
+        This license governs use of the CaptchaKraken software in this repository and of
+        the associated machine-learning model weights and LoRA adapters published by the
+        copyright holder (collectively, the "Software"). By using the Software you agree
+        to these terms. If you do not agree, do not use the Software.
+        
+        ================================================================================
+        1. GRANT
+        ================================================================================
+        Subject to the restrictions below, you are granted a worldwide, royalty-free,
+        non-exclusive license to use, copy, modify, and distribute the Software, and to
+        incorporate it into your own products and services.
+        
+        ================================================================================
+        2. PERMITTED USES
+        ================================================================================
+        You MAY use the Software for:
+        
+          (a) Personal, non-commercial use, research, and education.
+        
+          (b) Commercial use INSIDE a larger product or service that delivers
+              substantial value BEYOND captcha solving itself — that is, where captcha
+              solving is an internal, enabling component rather than the product.
+        
+          Illustrative (non-exhaustive) examples of PERMITTED commercial use:
+              - Web scrapers and data-collection pipelines.
+              - Stealth / anti-detection browsers and browser automation frameworks
+                that use the Software as one internal capability.
+              - QA, testing, and accessibility tooling.
+              - Any application where the captcha solve is a means to an end the user
+                is actually paying for.
+        
+        ================================================================================
+        3. PROHIBITED USES
+        ================================================================================
+        You MAY NOT, without a separate written commercial agreement from the copyright
+        holder:
+        
+          (a) Sell, resell, rent, or otherwise offer for a fee any captcha-SOLVING
+              service, product, or API whose primary value is solving captchas,
+              where that service is powered by the Software or its model outputs.
+        
+          (b) Distribute "thin wrappers" around the Software whose primary purpose is
+              captcha solving — including but not limited to browser extensions,
+              hosted endpoints, SaaS products, or CLIs that simply expose the
+              Software's solving capability to end users.
+        
+          (c) Expose, proxy, or relay the responses or outputs of the Software's LoRA
+              models (e.g. bounding boxes, tile selections, click plans) through a paid
+              or public API as a captcha-solving service.
+        
+          In short: you may BUILD WITH this Software, but you may not SELL THE SOLVE.
+        
+        ================================================================================
+        4. MODEL OUTPUTS
+        ================================================================================
+        Outputs produced by the model weights/adapters are subject to Sections 2 and 3
+        to the same extent as the Software itself. Reselling or API-relaying those
+        outputs as a captcha-solving service is prohibited under Section 3(c).
+        
+        ================================================================================
+        5. REDISTRIBUTION
+        ================================================================================
+        If you redistribute the Software (modified or not), you must retain this license
+        and this notice, and you must not remove or alter the restrictions in Section 3.
+        
+        ================================================================================
+        6. TRADEMARKS
+        ================================================================================
+        This license does not grant permission to use the trade names, trademarks, or
+        product names of the copyright holder, except as required to describe the origin
+        of the Software.
+        
+        ================================================================================
+        7. NO WARRANTY
+        ================================================================================
+        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.
+        
+        ================================================================================
+        8. RESPONSIBLE USE
+        ================================================================================
+        You are responsible for ensuring your use of the Software complies with all
+        applicable laws, the terms of service of any site you interact with, and
+        applicable anti-fraud and computer-access statutes. The copyright holder does
+        not endorse using the Software to violate any third party's terms or rights.
+        
+        ================================================================================
+        9. COMMERCIAL LICENSING
+        ================================================================================
+        For uses prohibited under Section 3 — including selling captcha-solving as a
+        service — contact the copyright holder to discuss a separate commercial license.
+        
+        --------------------------------------------------------------------------------
+        This text is a license, not legal advice. If the boundary between a permitted
+        "value-add" product and a prohibited "thin wrapper" is unclear for your use
+        case, ask by opening an issue or messaging the maintainer on GitHub:
+        https://github.com/JWriter20/CaptchaKraken
+        --------------------------------------------------------------------------------
+License-File: LICENSE
+Keywords: automation,captcha,computer-vision,hcaptcha,qwen,recaptcha,vllm
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python-headless>=4.10.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: accelerate>=0.27.0; extra == 'serve'
+Requires-Dist: huggingface-hub>=0.23.0; extra == 'serve'
+Requires-Dist: torch>=2.0.0; extra == 'serve'
+Requires-Dist: transformers>=4.40.0; extra == 'serve'
+Requires-Dist: vllm>=0.6.3; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# captchakraken
+
+The Python engine + CLI behind [CaptchaKraken](https://github.com/JWriter20/CaptchaKraken):
+OpenCV grid detection + a fine-tuned **Qwen3.5-9B** vision LoRA served on
+**vLLM**. Given a screenshot of a captcha grid, it locates the tiles and returns
+the click plan. Ships the `captchakraken` command.
+
+> For demo videos, accuracy numbers, the browser driver, and the full
+> self-hosting guide, see the main repo
+> **[CaptchaKraken](https://github.com/JWriter20/CaptchaKraken)**.
+
+## Install
+
+```bash
+pip install captchakraken            # client: OpenCV detection + vLLM HTTP planner
+pip install "captchakraken[serve]"   # + the serving stack (vLLM/torch) to self-host
+```
+
+The base install is lightweight — everything you need to solve captchas against
+a vLLM server (local or remote). The `[serve]` extra pulls the heavy stack only
+if you want to run the model yourself. The one-command
+[`setup.sh`](https://github.com/JWriter20/CaptchaKraken) installs `[serve]`,
+downloads the weights, and writes an env file for you.
+
+## Hands-off server
+
+The vLLM server is managed for you. On your first solve, if the configured
+endpoint is **local** and nothing is listening, a server is started
+automatically and reused. Point `VLLM_BASE_URL` at a server you already run to
+skip local management entirely.
+
+```bash
+captchakraken server start | stop | status | run
+```
+
+## Usage
+
+```bash
+# Solve an image/video: classify → find_grid → plan. Prints the click actions.
+captchakraken path/to/captcha.png
+captchakraken path/to/captcha.png --puzzle-source hcaptcha
+```
+
+```python
+from captchakraken import CaptchaSolver
+
+solver = CaptchaSolver()          # connects to / auto-starts a local vLLM
+actions = solver.solve("captcha.png")
+```
+
+Pure-OpenCV tool subcommands (no model): `find-grid`, `find-checkbox`,
+`detect-selected`, `grid-cell-states`, `find-move`, `find-movable`, and a
+persistent `serve` worker the browser driver polls.
+
+## Configuration (model-agnostic)
+
+Everything model-specific lives in `captchakraken.config` and is env-overridable
+— the solver never hard-codes a model.
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `VLLM_BASE_URL` | Inference endpoint | `http://localhost:8000/v1` |
+| `CAPTCHA_KRAKEN_API_KEY` | Bearer token (`VLLM_API_KEY` also accepted) | `EMPTY` |
+| `CAPTCHA_BASE_MODEL` | Base weights vLLM loads | `Qwen/Qwen3.5-9B` |
+| `CAPTCHA_LORA_ADAPTER` | Captcha adapter (HF id or path) | `CaptchaKraken/CaptchaKraken_v1` |
+| `CAPTCHA_LORA_NAME` | Served adapter name the client requests | `captcha` |
+| `CAPTCHA_KRAKEN_AUTOSTART` | `0` disables local auto-start | `1` |
+
+## License
+
+**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
+Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
+solve itself** or ship a thin wrapper (browser extension, hosted solving API).

{captchakraken-2.2.0 → captchakraken-2.3.0}/README.md

@@ -68,4 +68,6 @@ Everything model-specific lives in `captchakraken.config` and is env-overridable
 
 ## License
 
-GPL-3.0-or-later.
+**CaptchaKraken Source-Available License v1.0** — see [LICENSE](./LICENSE).
+Build *with* it (scrapers, stealth browsers, QA tooling); you may **not sell the
+solve itself** or ship a thin wrapper (browser extension, hosted solving API).

{captchakraken-2.2.0 → captchakraken-2.3.0}/pyproject.toml

@@ -4,17 +4,21 @@ build-backend = "hatchling.build"
 
 [project]
 name = "captchakraken"
-version = "2.2.0"
+version = "2.3.0"
 description = "Self-hosted captcha solver: OpenCV grid detection + a fine-tuned Qwen3.5-9B vision LoRA served on vLLM."
 readme = "README.md"
 requires-python = ">=3.10"
-license = { text = "GPL-3.0-or-later" }
+# Source-available, NOT GPL. The CaptchaKraken Source-Available License permits
+# commercial use as an internal component but prohibits selling the solve itself
+# or thin-wrapper resale — see LICENSE. (GPL-3.0 would wrongly permit reselling.)
+license = { file = "LICENSE" }
 authors = [{ name = "Jake Writer" }]
 keywords = ["captcha", "recaptcha", "hcaptcha", "vllm", "qwen", "computer-vision", "automation"]
 classifiers = [
   "Programming Language :: Python :: 3",
   "Operating System :: OS Independent",
   "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "License :: Other/Proprietary License",
 ]
 
 # Core = the lightweight CLIENT: OpenCV grid detection + the HTTP planner that

{captchakraken-2.2.0 → captchakraken-2.3.0}/src/captchakraken/__init__.py

@@ -40,14 +40,26 @@ from .overlay import add_overlays_to_image
 try:  # pragma: no cover - exercised only when the serving stack is installed
     from .planner import ActionPlanner
     from .solver import CaptchaSolver, solve_captcha
+
+    # The page driver sits behind the same guard: it imports `solver`, so it has
+    # the same dependency floor. It needs NO browser package of its own — the
+    # caller supplies the Playwright-compatible page (see page_solver's module
+    # docstring on why we duck-type rather than import one).
+    from .page_solver import PageSolver, SolveResult, solve_captcha_on_page
 except ModuleNotFoundError:
     ActionPlanner = None  # type: ignore[assignment,misc]
     CaptchaSolver = None  # type: ignore[assignment,misc]
     solve_captcha = None  # type: ignore[assignment]
+    PageSolver = None  # type: ignore[assignment,misc]
+    SolveResult = None  # type: ignore[assignment,misc]
+    solve_captcha_on_page = None  # type: ignore[assignment]
 
 __all__ = [
     "CaptchaSolver",
     "solve_captcha",
+    "PageSolver",
+    "SolveResult",
+    "solve_captcha_on_page",
     "ActionPlanner",
     "ImageProcessor",
     "CaptchaAction",
@@ -58,4 +70,4 @@ __all__ = [
     "add_overlays_to_image",
 ]
 
-__version__ = "2.0.0"
+__version__ = "2.3.0"

{captchakraken-2.2.0 → captchakraken-2.3.0}/src/captchakraken/cli.py

@@ -42,11 +42,18 @@ Modes:
         these — a local server auto-starts on the first solve (disable with
         CAPTCHA_KRAKEN_AUTOSTART=0). Point VLLM_BASE_URL at your own server to
         skip local management entirely.
+
+  captchakraken fetch [--weights-only|--engine-only] [--no-restart] [--dry-run]
+        Update in one step: pull the latest CaptchaKraken model from the HF org
+        (https://huggingface.co/CaptchaKraken) AND upgrade the vLLM serving
+        stack, then restart a running local server so it takes effect. Use this
+        to get new model revisions + engine fixes without re-running setup.sh.
 """
 
 import argparse
 import json
 import os
+import subprocess
 import sys
 
 from .solver import CaptchaSolver, UnsupportedCaptchaError
@@ -372,6 +379,7 @@ def _handle_serve() -> bool:
       find-grid               {image}                       -> grid_boxes | null
       grid-cell-states        {a, b}                        -> states | {grid: null}
       grid-cell-states-fixed  {a, b, grid_boxes}            -> states
+      check-movement          {a, b, threshold?}            -> {has_movement: bool}
 
     Unknown cmd / malformed line -> an {ok:false} response (the process keeps
     running). EOF on stdin ends the loop cleanly. All heavy detection delegates
@@ -396,6 +404,15 @@ def _handle_serve() -> bool:
             if not grid_boxes:
                 raise ValueError("empty grid_boxes")
             return _compute_grid_cell_states(req["a"], req["b"], grid_boxes)
+        if cmd == "check-movement":
+            # Freshness check for the JS solver: did the captcha frame change
+            # (tiles faded in / refreshed) between the screenshot we sent the
+            # model and now? Same primitive the one-shot `check-movement` uses.
+            from .image_processor import ImageProcessor
+
+            threshold = float(req.get("threshold", 0.005))
+            moved = ImageProcessor.detect_movement(req["a"], req["b"], threshold)
+            return {"has_movement": bool(moved)}
         raise ValueError(f"unknown cmd: {cmd!r}")
 
     # Signal readiness so the JS side knows imports are done before it polls.
@@ -560,9 +577,55 @@ def _handle_server_commands() -> bool:
     return True
 
 
+def _handle_fetch() -> bool:
+    """`captchakraken fetch` — pull the latest published weights from the HF org
+    and refresh the vLLM serving stack, restarting a running local server so the
+    update takes effect. See updater.fetch for the full behavior."""
+    if len(sys.argv) <= 1 or sys.argv[1] not in {"fetch", "update"}:
+        return False
+
+    flags = set(sys.argv[2:])
+    unknown = flags - {"--weights-only", "--engine-only", "--no-restart", "--dry-run"}
+    if unknown:
+        print(
+            json.dumps({"error": f"unknown fetch flag(s): {sorted(unknown)} "
+                                 "(use --weights-only|--engine-only|--no-restart|--dry-run)"}),
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    if "--weights-only" in flags and "--engine-only" in flags:
+        print(json.dumps({"error": "--weights-only and --engine-only are mutually exclusive"}),
+              file=sys.stderr)
+        sys.exit(2)
+
+    from . import updater
+
+    weights = "--engine-only" not in flags
+    engine = "--weights-only" not in flags
+    try:
+        result = updater.fetch(
+            weights=weights,
+            engine=engine,
+            restart="--no-restart" not in flags,
+            dry_run="--dry-run" in flags,
+        )
+        print(json.dumps(result))
+        return True
+    except subprocess.CalledProcessError as e:
+        print(json.dumps({"error": f"fetch step failed (exit {e.returncode}): "
+                                   f"{' '.join(e.cmd) if isinstance(e.cmd, list) else e.cmd}"}),
+              file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(json.dumps({"error": str(e)}), file=sys.stderr)
+        sys.exit(1)
+
+
 def main():
     if _handle_server_commands():
         return
+    if _handle_fetch():
+        return
     if _handle_movement_commands():
         return
     if _handle_move_commands():

captchakraken-2.3.0/src/captchakraken/config.py

@@ -0,0 +1,160 @@
+"""
+Central, model-agnostic configuration for CaptchaKraken.
+
+Every model-specific value lives here and is overridable via environment
+variables, so swapping the underlying model never requires touching the solver,
+planner, or CLI. The defaults point at the published unified captcha LoRA, but
+nothing in the codebase hard-codes a model name outside this module.
+
+The two variables MOST users ever set:
+  VLLM_BASE_URL           where inference requests go (local or a remote server)
+  CAPTCHA_KRAKEN_API_KEY  bearer token for that server
+
+Advanced / self-hosting overrides (only needed to change WHICH model is served):
+  CAPTCHA_BASE_MODEL      base weights vLLM loads         (HF id or local path)
+  CAPTCHA_LORA_ADAPTER    LoRA applied on top             (HF id or local path)
+  CAPTCHA_LORA_REVISION   adapter git revision to serve
+  CAPTCHA_LORA_NAME       served adapter name the client asks for as `model`
+
+Defaults for the model-identity values come from `pinned_model.json` (see
+`pinned()`), which records the model + prompt pair this release was validated
+against.
+  VLLM_PORT, VLLM_GPU_MEMORY_UTILIZATION, VLLM_MAX_MODEL_LEN, VLLM_MAX_LORA_RANK
+  CAPTCHA_KRAKEN_AUTOSTART=0   disable auto-starting a local server on first use
+"""
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+_PINNED_MODEL_PATH = Path(__file__).with_name("pinned_model.json")
+
+
+@lru_cache(maxsize=1)
+def pinned() -> Dict[str, Any]:
+    """The pinned model manifest shipped with this release.
+
+    Defines the (base model, adapter, serving prompts) triple this version was
+    validated against. Env vars still override every value below — the manifest
+    supplies the DEFAULT and gives CI something to assert against, so an adapter
+    or prompt change is a reviewable diff instead of a silent drift.
+    """
+    with _PINNED_MODEL_PATH.open(encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ── Inference endpoint ──────────────────────────────────────────────────────
+def base_url() -> str:
+    """OpenAI-compatible endpoint, e.g. http://localhost:8000/v1."""
+    return os.getenv("VLLM_BASE_URL", f"http://localhost:{port()}/v1")
+
+
+def state_dir() -> Path:
+    """Shared state dir for the pidfile, lockfile, server log, and credentials."""
+    return Path(os.getenv("CAPTCHA_KRAKEN_STATE_DIR", str(Path.home() / ".captchakraken")))
+
+
+def credentials_path() -> Path:
+    return state_dir() / "credentials"
+
+
+def _key_from_credentials_file() -> str:
+    """Key written by the MCP server's signup flow (or a future `login` command).
+
+    Hosted-API onboarding writes the key to a 0600 file rather than returning it
+    through the agent transcript, so it never lands in an LLM context window.
+    Reading it here is what lets a solve authenticate with NO env vars set.
+
+    Deliberately tolerant of a bare token, an env-file line, or surrounding
+    quotes: the file is written by a *separate* tool, and a format mismatch here
+    would surface as a baffling 401 rather than an obvious parse error.
+    Returns "" whenever the file is missing, unreadable, or has no usable line.
+    """
+    try:
+        text = credentials_path().read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            name, _, value = line.partition("=")
+            # An env-file with unrelated keys must not yield a bogus token.
+            if name.strip() not in {"CAPTCHA_KRAKEN_API_KEY", "VLLM_API_KEY"}:
+                continue
+            line = value.strip()
+        return line.strip("'\"")
+
+    return ""
+
+
+def api_key() -> str:
+    """Bearer token, in precedence order.
+
+    Env first so an explicit override always wins, then the credentials file so
+    the MCP/hosted path needs no env plumbing at all, then "EMPTY" (which leaves
+    a self-hosted local vLLM open, as before).
+    """
+    return (
+        os.getenv("CAPTCHA_KRAKEN_API_KEY")
+        or os.getenv("VLLM_API_KEY")
+        or _key_from_credentials_file()
+        or "EMPTY"
+    )
+
+
+# ── Model identity (all overridable — the CLI itself is model-agnostic) ──────
+def base_model() -> str:
+    return os.getenv("CAPTCHA_BASE_MODEL", pinned()["base_model"])
+
+
+def lora_adapter() -> str:
+    """HF repo id or local path of the captcha adapter served on top of the base."""
+    return os.getenv("CAPTCHA_LORA_ADAPTER", pinned()["lora_adapter"])
+
+
+def lora_revision() -> str:
+    """Git revision of the adapter repo to serve — pinning this is what makes
+    'the adapter this release was tested against' a reproducible statement."""
+    return os.getenv("CAPTCHA_LORA_REVISION", pinned()["lora_revision"])
+
+
+def lora_name() -> str:
+    """The served LoRA name the client sends as the `model` field."""
+    return os.getenv("CAPTCHA_LORA_NAME", pinned()["lora_name"])
+
+
+# ── Local vLLM server knobs ─────────────────────────────────────────────────
+def port() -> int:
+    return int(os.getenv("VLLM_PORT", "8000"))
+
+
+def gpu_memory_utilization() -> float:
+    return float(os.getenv("VLLM_GPU_MEMORY_UTILIZATION", "0.80"))
+
+
+def max_model_len() -> int:
+    return int(os.getenv("VLLM_MAX_MODEL_LEN", "65536"))
+
+
+def max_lora_rank() -> int:
+    return int(os.getenv("VLLM_MAX_LORA_RANK", "64"))
+
+
+def autostart_enabled() -> bool:
+    """Whether to auto-launch a local server on first use (default on)."""
+    return os.getenv("CAPTCHA_KRAKEN_AUTOSTART", "1") != "0"
+
+
+def extra_serve_args() -> list:
+    """Extra flags appended verbatim to `vllm serve` (space-separated).
+
+    Escape hatch for serving tweaks the config doesn't model directly — e.g.
+    `--enforce-eager` or a smaller `--max-num-seqs` to squeeze onto a tight GPU.
+    """
+    raw = os.getenv("VLLM_EXTRA_ARGS", "").strip()
+    return raw.split() if raw else []