llamacppctl/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

pip install -e ".[dev]"          # dev install
scripts/check.sh                 # full local CI gate (ruff + mypy + pytest) — mirrors .forgejo/workflows/ci.yml
python -m pytest -q              # tests
python -m pytest tests/test_prompt_urls.py -q            # one file
python -m pytest tests/test_actions.py::test_do_start -q # one test
ruff check src/ tests/ build_archive.py
mypy                             # config in pyproject.toml (files = src/llamacppctl)

Always use python -m pytest, never the pytest console script: the test modules do from tests.test_docker_ops import ..., which needs the repo root on sys.path.

git config core.hooksPath .githooks (once per clone) enables the pre-push hook that runs scripts/check.sh. CI runs on Python 3.10 and 3.12; requires-python = ">=3.10".

Other entry points:

• python3 build_archive.py — builds and self-verifies llamacppctl-installable.tar.gz (has its own required-file manifest; adding a top-level file that must ship means updating it).
• SMOKE_GPU=1 scripts/smoke.sh — opt-in end-to-end test against a real Docker + GPU + GGUF model. Not part of the pytest suite.

Architecture

A single CLI (llamacppctl) that starts/checks/stops/switches llama.cpp servers running as Docker containers, plus a security-hardened input layer for system/user prompts from text, file, or URL.

main.py is a thin pipeline: parse (cli.build_parser) → validate (cli.validate_args) → docker_available() → resolve prompt sources (prompt_io) → resolve config (config.resolve_effective_config) → dispatch to actions.do_*.

Layering is deliberate and must be preserved — it keeps the security-critical input validation independently testable from orchestration:

• prompt_io.py knows nothing about argparse; it works only with PromptSource + InputPolicy.
• config.py knows nothing about Docker or HTTP.
• docker_ops.py / http_ops.py know nothing about CLI semantics.
• actions.py orchestrates; schema.py holds the shared dataclasses (ServerConfig, PromptConfig, ChatReply, CheckResult).

Two cross-module couplings to know about:

• main._resolve_prompts() stashes loaded prompts on the argparse namespace as args._resolved_system_prompt / args._resolved_user_prompt; config.py picks them up there.
• main.run() calls docker_available() before config resolution, so --dry-run still needs a reachable Docker daemon. Only --print-effective-config skips that check — it is a standalone action in the mutually-exclusive group, never a modifier, so it cannot start anything.

Config resolution

INI file (llama.cpp.config, template in llama.cpp.config.example), lowest to highest priority: builtin defaults (config.builtin_defaults()) → [default] → [model.<profile>] (via --profile) → CLI overrides. [prompt.<name>] sections resolve separately and only supply a fallback system prompt — an explicit -s/--system-file/--system-url always wins.

container_name is mandatory (empty → ConfigError). It is the only identity anchor: Docker --name, the --stop/--check target, and the derived lock path /tmp/llamacppctl.<container_name>.lock. Profiles meant to run in parallel need distinct container_name and host_port, otherwise a second --start silently replaces the first container.

max_tokens / chat_temperature / connect_timeout / read_timeout affect only the chat request (--chat and the reply printed after --start), never the container.

Exit codes (actions.py)

0 ok · 1 general/config/prompt error · 2 argparse validation · 3 model path missing · 4 docker error · 5 HTTP not ready (also --check failing) · 6 lock busy. --check is meant to be scriptable; keep those codes stable.

Invariants worth not breaking

• All Docker calls go through subprocess.run() with argument lists — never shell=True, never composed shell strings.
• The port publishes to 127.0.0.1 by default (docker_ops._port_publish()); the llama.cpp OpenAI endpoint is unauthenticated unless api_key is set. --expose binds all interfaces.
• Every HTTP request in prompt_io — including each redirect hop — passes validate_url_target(): HTTPS-only, no IP literals, no embedded credentials, no localhost, all resolved addresses classified (private/loopback/link-local/multicast/reserved/unspecified → reject), metadata IP 169.254.169.254 blocked. _pin_dns() then restricts getaddrinfo to the already-validated IPs for the duration of the request, closing the TOCTOU/DNS-rebinding window. Size limits are enforced both from Content-Length and while streaming.
• Escape hatches (--allow-private-url, --allow-insecure-http, --allow-ip-host, --allow-symlinks, --follow-redirects, --allow-html-input) are opt-in and off by default. --allow-private-url and --url-allow-host are mutually exclusive.
• --start and --change hold an exclusive non-blocking fcntl.flock; --change validates the model path before removing the running container. --dry-run takes no lock and touches nothing.

Tests mock subprocess and requests (and DNS resolution for the SSRF cases); nothing in the pytest suite requires Docker or the network.

Conventions

• Docs, comments in docs/, and the example prompts are in German; source code, docstrings, and commit subjects are in English. Commits follow Conventional Commits (feat(chat):, docs(prompts):).
• Line length 100, from __future__ import annotations in every module, py.typed is shipped — keep annotations complete enough for mypy to pass.
• Behavior changes should be reflected in man/llamacppctl.1, CHANGELOG.md, and — for security- relevant ones — docs/SECURITY_AND_OPERATIONS.md.