Skip to main content

CastleArq

CastleArq is a command-line tool for running local GGUF models with llama.cpp that checks whether a model can run on your machine — and shows its work — before running it.

CastleArq does not replace llama.cpp and does not perform inference itself. llama.cpp is the runtime that loads the model and generates text. CastleArq manages model files, evaluates compatibility, applies admission and orchestrates execution against that runtime.

Version note. The current release candidate is 0.5.1; it has not yet been tagged or published. This release adds read-only search and inspect commands, uses acquisition resolution as the production acquisition path, and blocks a requested revision that conflicts with the stored artifact without replacing the existing artifact. Local GGUF files can still be brought into the model store with import, and the validate command remains available. It requires Python 3.11 or newer.

What problem does it solve?

You have GGUF model files and a local llama.cpp runtime. Pointing llama-cli at a model gives you either output or a failure, and nothing in between: no answer to why it failed, and no way to know in advance whether it could have worked at all on this machine, with this artifact, on this runtime.

CastleArq answers that question first, with evidence, and refuses to run what it cannot justify running.

How it works

runtime       -> inspect the llama.cpp runtime that is actually installed
models        -> catalog of candidate models for this machine
download      -> fetch a GGUF artifact (the model file) and store it locally
list          -> locally stored artifacts and their derived state
validate      -> validate one stored artifact: filesystem, size, integrity
compatibility -> evaluate five conditions and print the evidence
execute       -> refuse or run, according to that evaluation

Why compatibility evidence matters

The compatibility evaluation checks exactly five named conditions between one specific artifact and the detected runtime:

Condition Question
artifact–model identity is this file the model that was asked for?
artifact format support does the runtime accept this file format?
model architecture support does the runtime know this architecture?
runtime artifact support does the runtime report supporting this artifact?
runtime backend support does the selected backend support this model?

Each condition is reported with what was Expected, what was Observed, and the Evidence recorded for that observation. A condition is PASSED, FAILED, or UNKNOWN — and UNKNOWN is reported as UNKNOWN. It is never silently converted into a failure.

When the evaluation does not admit the model, admission — the decision that allows or refuses execution — refuses it, and the run does not happen. There is no flag to force execution past a refusal.

The same admission policy applies to every surface that runs a model: the execute command, POST /v1/run over HTTP, and opening a chat session.

Throughout this document:

  • model — the logical model you want to use;
  • MODEL_ID — the canonical identifier the CLI accepts. For an artifact brought in with import, that value is the label import reports and list shows; the model's logical identity can remain UNKNOWN;
  • artifact — the concrete model file (GGUF) stored locally;
  • quantization — the chosen size/precision variant of that file;
  • runtime — the llama.cpp installation that loads and runs the model.

Installation

pip install castlearq

From a checkout:

python3 -m venv .venv
. .venv/bin/activate
pip install .
castlearq --version

A previously built wheel or sdist can also be installed, for example pip install dist/castlearq-0.5.1-py3-none-any.whl. Installation needs neither PYTHONPATH nor the source tree afterwards, and the package contains no models.

Requirements

CastleArq is for developers already working with local AI models on Linux who have, or can obtain, llama.cpp, and who use GGUF files. It is not a consumer application.

You need:

  • Linux as the exercised baseline.
  • Python 3.11 or newer.
  • llama.cpp provided externally. CastleArq does not install, build or vendor it, and does not ship models, drivers, Vulkan, CUDA or ROCm. The official llama launcher must be on your PATH.
  • Disk space for model files. A single 7B Q4_K_M artifact is roughly 4.4 GiB.

The normal flow does not require sudo and does not modify your system.

Runtime setup

CastleArq requires the llama executable; it does not install or build llama.cpp. First check that the launcher is on your PATH:

command -v llama

Then inspect the state CastleArq can observe:

castlearq runtime

The output shows the runtime, launcher, resolved executable, version, build, availability and detected capabilities.

State Meaning Action
AVAILABLE runtime usable continue with models
NOT_FOUND llama is not available provide llama.cpp externally
FOUND_UNUSABLE a path was found but is not usable check path, permissions and file type
PROBE_ERROR validation could not complete read reason, check the llama.cpp install/build
UNKNOWN not enough evidence read reason and re-run the diagnostic

llama is the official launcher. llama-cli, llama-server and llama.app do not automatically stand in for llama in CastleArq 0.5.x.

Quick start

There are two routes, depending on whether you already have a model file. Both end in the same commands; they differ only in where the artifact comes from.

Route A: you already have a local GGUF

# 1. Check the runtime CastleArq will drive
castlearq runtime

# 2. Import the file you already have; it reports the label to use next
castlearq import ./my-model.gguf

# 3. See what is stored and in what state
castlearq list

# 4. Validate that stored artifact: filesystem, size, integrity
castlearq validate <LABEL>

# 5. Check it can run here, and see the evidence
castlearq compatibility <LABEL>

# 6. Run a prompt
castlearq execute <LABEL> "Reply with exactly: OK"

import runs nothing: it copies the file into the model store and prints the label you use as <LABEL> in the commands after it. The label is the operational identifier of the artifact, not a statement about which model the file is; a local file carries no evidence of that, so its logical identity may stay UNKNOWN.

Route B: you need to get a model from the catalog

# 1. Check the runtime CastleArq will drive
castlearq runtime

# 2. See which models are candidates for this machine
castlearq models

# 3. Fetch one explicitly (multi-GB download)
castlearq download qwen2.5-coder-7b-instruct

# 4. See what is stored and in what state
castlearq list

# 5. Validate that stored artifact: filesystem, size, integrity
castlearq validate qwen2.5-coder-7b-instruct

# 6. Check it can run here, and see the evidence
castlearq compatibility qwen2.5-coder-7b-instruct

# 7. Run a prompt
castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: OK"

From here on, MODEL_ID means whatever identifier list shows for the artifact you want to work with: a catalog model id after download, or the label after import. For an imported artifact, that label is only the operational handle — the model's logical identity can remain UNKNOWN.

list shows each stored artifact and its derived state; validate re-checks one artifact on demand and reports what it can and cannot prove. Both are read-only and neither changes what may run. compatibility is a normal step in this flow, not optional troubleshooting: it is the same evaluation execute uses to decide whether to run.

Check compatibility before running anything

castlearq compatibility qwen2.5-coder-7b-instruct

This command is read-only: it runs no inference, starts no runtime, downloads nothing, does not modify the model store and creates no persistent state. It prints the verdict and, for each condition, its status, what was expected, what was observed, and the evidence already recorded.

Abridged output (the real command prints all five conditions):

Compatibility evaluation
  Model: qwen2.5-coder-7b-instruct
  Artifact: qwen2.5-coder-7b-instruct-q4_k_m.gguf (Q4_K_M)
  Runtime: llama.cpp CLI
  Verdict: INSUFFICIENT_EVIDENCE

Checks:
  artifact format support: PASSED
    Expected: 'gguf'
    Observed: 'gguf'
    Evidence (observed): artifact.format = 'gguf'
  runtime artifact support: UNKNOWN
    Evidence (observed): runtime.supports_artifact = None

Exit codes: 0 when the evaluation admits execution, 1 when it does not, 2 on incorrect usage.

The criterion is the same one execute uses: this command reports, it does not change policy.

INSUFFICIENT_EVIDENCE does not mean incompatible

INSUFFICIENT_EVIDENCE is the overall verdict when not every condition has sufficient evidence. It does not assert that the model is incompatible; it asserts that CastleArq does not know enough to assert either way.

The actual behaviour, which compatibility does not alter:

  • if any condition is FAILED, a failure is demonstrated and execution is refused;
  • if the only conditions without evidence are the ones that do not depend on a prior evaluation, CastleArq treats them as non-blocking and admits execution. That is why you can see Verdict: INSUFFICIENT_EVIDENCE together with exit code 0: the verdict is honest about what it does not know, and the admission is equally honest about what it does.

UNKNOWN never becomes FAILED, and INSUFFICIENT_EVIDENCE never automatically becomes "not compatible". To know whether a given model is blocked, the admission result decides — not the name of the verdict.

First execution

castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: OK"

A successful prompt prints the model's response on stdout. The runtime may print loading and generation messages, and CastleArq may print warnings on stderr. A warning does not by itself mean the execution failed.

  • exit code 0: success;
  • exit code 1: operational failure;
  • exit code 2: incorrect arguments or usage.

Exact output varies with the model and prompt. A successful result includes generated output and code 0.

execute versus run

The legacy run interface also exists and reaches the same llama.cpp runtime:

castlearq run qwen2.5-coder-7b-instruct --prompt "Reply with exactly: OK"

They are not equivalent in policy:

execute run
Prompt positional --prompt
Strict evaluation before running yes no
Admission yes no
Runtime llama.cpp llama.cpp

execute evaluates compatibility strictly and refuses to run when admission denies it, showing the conditions, reasons and evidence. run is the legacy interface: it reaches the same runtime through the legacy preparation path and does not apply strict evaluation admission.

Use execute. run is kept for compatibility.

A real run

The transcript below was captured from a real execution on Linux with llama.cpp 0.4.0-dev and a real 4.4 GiB Q4_K_M artifact, using the commands above. Nothing in it is hand-written.

castlearq compatibility qwen2.5-coder-7b-instruct:

Compatibility evaluation
  Model: qwen2.5-coder-7b-instruct
  Artifact: qwen2.5-coder-7b-instruct-q4_k_m.gguf (Q4_K_M)
  Runtime: llama.cpp CLI
  Verdict: INSUFFICIENT_EVIDENCE

Checks:
  artifact-model identity: PASSED
    Expected: 'qwen2.5-coder-7b-instruct'
    Observed: 'qwen2.5-coder-7b-instruct'
    Evidence (observed): model.identity.model_id = 'qwen2.5-coder-7b-instruct'
    Evidence (observed): artifact.identifier = 'qwen2.5-coder-7b-instruct'
  artifact format support: PASSED
    Expected: 'gguf'
    Observed: 'gguf'
    Evidence (observed): artifact.format = 'gguf'
    Evidence (observed): runtime.supported_formats = 'gguf'
    Evidence (observed): runtime.unsupported_formats = None
  model architecture support: PASSED
    Expected: 'qwen2'
    Observed: 'qwen2'
    Evidence (observed): model.architecture = 'qwen2'
    Evidence (observed): runtime.architecture_knowledge = 'explicit lists'
  runtime artifact support: UNKNOWN
    Evidence (observed): runtime.name = 'llama.cpp'
    Evidence (observed): runtime.supports_artifact = None
  runtime backend support: UNKNOWN
    Evidence (observed): context.backend = None
    Evidence (observed): runtime.supported_backends = 'cpu, cuda, hip'
    Evidence (observed): runtime.unsupported_backends = None

Read it honestly: three conditions passed with evidence; two are UNKNOWN because the runtime reports nothing for them. CastleArq reports INSUFFICIENT_EVIDENCE rather than inventing a pass, and admission still allows the run because those two conditions are not blocking.

castlearq execute qwen2.5-coder-7b-instruct "Reply with exactly: CASTLEARQ_OK" (llama.cpp's own loading banner elided, indicated below):

Warning: Model memory is an estimate.

[... llama.cpp loading banner and runtime command help elided ...]

> Reply with exactly: CASTLEARQ_OK
CASTLEARQ_OK

[ Prompt: 258.1 t/s | Generation: 38.0 t/s ]

The command exited 0 and the model produced exactly the requested token sequence. The Warning: line comes from CastleArq's own memory estimation, which is separate from the five-condition verdict — see What the verdict does not cover.

Model management

Artifacts reach CastleArq from one of two sources, and both lead to the same place:

catalog:     models -> download MODEL_ID -> list -> execute
local file:  import PATH -> list -> execute

models shows the catalog and its per-machine recommendations; it is about candidates, not about what you have. list shows the managed artifacts available for use, whether they arrived through download or through import. An imported GGUF therefore does not appear in models: models is the catalog, list is your store, and CastleArq keeps them apart.

For a downloaded artifact, the model id is the identifier later commands take. For an imported one, that identifier is the label reported by import and shown by list. The label is an operational handle, not a claim about the model's logical identity, which a local file provides no evidence for and which may stay UNKNOWN.

The catalog cycle is:

models -> choose MODEL_ID -> download -> list -> execute

download acquires the artifact explicitly, and repeating execute does not download the model again.

models prints, per candidate, the recommended quantization, an estimated memory figure, the selected runtime and backend, the reason, and any warning. Those recommendations come from CastleArq's memory estimation and hardware assessment, which are not the five-condition compatibility verdict.

To pick a specific variant:

castlearq download MODEL_ID --quantization QUANTIZATION
castlearq download MODEL_ID --filename MODEL_FILE.gguf

A download requires network access to the remote source, and CastleArq does not assume a remote model stays available forever.

Verify local artifacts

castlearq list

list shows locally stored artifacts with their model id, filename, quantization, size and verification state. Artifacts are reused by later runs. An artifact brought in with import appears here under its label, which is the value to pass to the commands below in its place.

To validate one stored artifact explicitly, use validate:

castlearq validate MODEL_ID

validate reports three independent dimensions, each PASSED, FAILED or UNKNOWN:

Dimension What it proves
safety the artifact exists, is a regular non-symlink file at its declared path, is complete, and can be opened without following a link
size the artifact matches size_bytes when the manifest declares one
integrity the artifact matches the declared SHA-256 when the manifest declares one

An artifact without a declared SHA-256 reports integrity: UNKNOWN:

qwen2.5-coder-7b-instruct / qwen2.5-coder-7b-instruct-Q4_K_M.gguf
  size: UNKNOWN
    no size is declared in the manifest;
  integrity: UNKNOWN
    no SHA-256 is declared in the manifest;
    no content comparison was performed
Artifact state: DOWNLOADED

UNKNOWN means insufficient evidence to decide. It is never reported as a pass and never as a failure: CastleArq did not compare the contents against anything, and it says so. An artifact with no declared SHA-256 is still executable, exactly as before.

validate is a read-only inspection: it changes nothing, never modifies or re-derives the artifact, and adds --quantization / --filename to select which artifact to validate.

The model store is independent of the checkout. CastleArq selects it from the first source you declare, in this order of authority:

Declared source Store used
castlearq --model-store PATH ... PATH, for that one invocation
[models] directory in config.toml the configured directory
XDG_DATA_HOME $XDG_DATA_HOME/castlearq/models
nothing declared ~/.local/share/castlearq/models
nothing declared, and no CastleArq store exists yet ~/.local/share/localai-hub/models (legacy compatibility)

Explicit configuration always wins, and directory existence does not decide the winner: a store you select is used even when its directory does not exist yet, is empty, or sits next to another store. Resolving the path does not create anything; the directory appears only when an operation actually writes to it.

To see which store is in use:

castlearq store
Store
Path: /home/you/.local/share/castlearq/models
Source: default
Exists: no
Legacy detected: yes
Legacy used: no

Source names the source that won: cli, config, xdg, default or legacy-compatibility. store is read-only.

The user configuration file is $XDG_CONFIG_HOME/castlearq/config.toml, falling back to ~/.config/castlearq/config.toml, and it selects the store with:

[models]
directory = "~/.local/share/castlearq/models"

The config/config.toml in the repository is a sample of that schema, not a file CastleArq reads at runtime.

~/.local/share/localai-hub/models is the path used by the predecessor local installation. It is a compatibility fallback and nothing more: it is selected only when you declared no store at all, the CastleArq store does not exist, and the legacy store does. When that happens, CastleArq says so on stderr, and it uses the artifacts where they already are. CastleArq does not migrate, move, copy or delete models, so you never need to edit manifests or relocate models by hand.

--model-store PATH selects the store for one invocation only:

castlearq --model-store /path/to/store list

How this differs from using llama.cpp directly

CastleArq drives llama.cpp; it does not replace it and does not perform inference itself. llama.cpp is the runtime that loads the model and generates text. CastleArq manages artifacts, evaluates compatibility, applies admission and orchestrates execution against that runtime.

The difference is what happens before the runtime is invoked. Pointing llama-cli at a model starts generation immediately. CastleArq first reports which of five conditions it could verify, what it expected, what it observed, and what evidence it has — and then refuses to start generation when the evaluation does not admit the model.

CastleArq makes no claim to be better, faster, safer or more reliable than any other tool, and makes no comparison with other local-AI runtimes. What it claims is narrower and checkable: it evaluates those five conditions, shows the evidence, and does not run what it cannot justify running.

What the verdict does not cover

The compatibility verdict is evidence about five named conditions between one artifact and one detected runtime. Reading it as anything broader would be a misreading, so this is stated explicitly.

The verdict does not establish:

  • memory sufficiency. It is not a RAM/VRAM capacity check. CastleArq's memory estimation is a separate, approximate heuristic reported separately (as a Warning: line), and it is labelled as an estimate.
  • output quality, model quality or semantic correctness of anything generated.
  • model behaviour — the verdict says nothing about what a model will say.
  • security or safety. CastleArq is not a sandbox and provides no isolation or hardening. A model that passes admission is not thereby safe to run.
  • performance. No speed, throughput or latency claim is made or measured.
  • absence of crashes or runtime failures. Admission is a decision made before generation; the runtime may still fail afterwards, and execute reports that as an operational failure.

Admission is also not a permission system. CastleArq has no identities, roles or accounts; the HTTP 403 status it returns for a refusal means "the evaluation did not admit this", not "you are not authorised".

A pass therefore means: these five conditions were checked and none of them demonstrably failed. It does not mean this model will run well.

HTTP API

castlearq serve

serve is not a status-only endpoint. It starts an HTTP API and performs real inference:

GET    /health                       -> liveness and version (this one is read-only)
GET    /v1/models                    -> catalog
GET    /v1/artifacts                 -> local artifacts
POST   /v1/run                       -> RUNS a prompt (real inference)
POST   /v1/chat/sessions             -> opens a live chat session
POST   /v1/chat/sessions/{id}/turns  -> sends a prompt to that session
GET    /v1/chat/sessions/{id}        -> session status
DELETE /v1/chat/sessions/{id}        -> closes the session

The server binds loopback (127.0.0.1) by default and rejects non-loopback hosts. That is a property of network exposure.

Execution policy is a separate matter, and the two should not be confused: HTTP execution applies the same strict evaluation admission as execute. Admission is a property of execution, not of the command or the transport. A model that strict evaluation does not admit is not executed over HTTP.

Status Meaning
200 success (model_id, output, exit_code, warnings)
400 malformed request
404 model not in the local catalog
409 an execution is already running (global lock, no queue)
403 admission denied by the compatibility evaluation
422 preparation failure (invalid artifact, no executable target)
500 evaluation error — the evaluation failed; this is not a denial
503 runtime unavailable, or the runner failed

A refusal returns only the admission summary:

{
  "error": "execution refused by compatibility admission",
  "admission": { "status": "evaluated", "verdict": "incompatible" }
}

Checks, diagnostics, evidence, local paths and exception details are never returned. For the full evaluation use castlearq compatibility MODEL_ID.

A 500 means the evaluation raised (for example an unreadable GGUF), not that it denied: that is why no verdict is shown. Execution is refused in both cases.

POST /v1/chat/sessions opens a live session, so it is subject to the same admission and the same global lock.

Limitations

Current, factual limitations of this release:

  • Linux is the exercised baseline. The code inspects other platforms, but only Linux has been run end to end.
  • llama.cpp is an external dependency. CastleArq does not install, build or vendor it. Without a working llama launcher, nothing can run.
  • Models are large. A 7B Q4_K_M artifact is roughly 4.4 GiB; downloads need network access, time and disk.
  • The catalog currently contains 3 models. castlearq models recommends from that small catalog, so treat it as a starting point rather than a broad index.
  • CastleArq does not perform inference itself. It orchestrates llama.cpp.
  • Memory figures are estimates. They are derived from parameter count and quantization, not measured, and are reported with a warning.
  • No quantization, scheduling, clustering or multi-GPU features. The backend is selected for the detected hardware; there is no workload scheduler.
  • One execution at a time. The HTTP surface serialises execution behind a single lock and answers 409 rather than queueing.
  • Blocked revision mismatch. A requested model revision that does not match the revision stored on disk is refused, and the already stored artifact is preserved; the download fails with a clear blocked error rather than replacing the existing file. Use another revision or another artifact instead.
  • No auth, TLS or persistence. serve is loopback-only by design; chat sessions live in memory only.

Troubleshooting

llama not found

command -v llama
castlearq runtime

If you see NOT_FOUND, provide llama.cpp externally and re-run castlearq runtime. CastleArq will not install it for you.

Runtime FOUND_UNUSABLE

CastleArq found a path it cannot use as a launcher. Check the reported path, permissions, file type, and the runtime install/build.

Runtime PROBE_ERROR

CastleArq found the launcher but could not validate its interface. Read Reason, check the llama.cpp install/build and re-run the diagnostic. This does not by itself demonstrate a universal incompatibility.

Artifact missing

castlearq list
castlearq models
castlearq download MODEL_ID

Artifact invalid or incomplete

Check castlearq list. Do not try to run an artifact whose state is not usable. If it is not downloaded, use download again; the existing command keeps its validation semantics and will not publish an artifact that fails its checks.

Incompatibility

Execution can be blocked by model, artifact, memory, quantization or capabilities. Check castlearq models, castlearq list and castlearq runtime before choosing a different artifact or prompt.

Backend unavailable

castlearq runtime

Do not assume a backend advertised by the hardware is available in the runtime. Use a backend compatible with what was detected.

Admission denied

CastleArq blocked execution according to the current evaluation. The output includes the full evaluation that produced the block: the verdict, each condition with its status, what was expected, what was observed, and the evidence. There is no instruction to force execution.

castlearq compatibility MODEL_ID

shows that same evaluation without running anything, and is the recommended way to understand the reason before trying again.

A UNKNOWN condition is not a failure: it means there is not enough evidence, and it is not treated as an incompatibility.

Compatibility evaluation error

If the evaluation could not complete, CastleArq says so explicitly:

Compatibility evaluation error: GGUFReadError: ...

This is not a policy denial: it means the evaluation failed. The reported cause (for example a corrupt or unreadable GGUF) is the real problem, and execution remains blocked. Check the artifact with castlearq list and re-download it if its state is not usable.

Execution failure

Check the error and the execution's stderr, and compare:

castlearq runtime
castlearq list

A process failure does not automatically mean the runtime or the artifact is missing.

Download failure

Check connectivity, remote source availability, the MODEL_ID, the quantization/filename selection, and re-run:

castlearq download MODEL_ID

CLI usage error

castlearq --help

Exit code 2 indicates incorrect usage, such as missing arguments or invalid flags.

Command reference

Command What it does
models Catalog with recommendations scored against the detected hardware
download MODEL_ID Explicitly fetch a GGUF artifact
import PATH Imports a local GGUF file into the model store
list Locally stored artifacts and their state
store Reports the model store in use: path, source, existence, legacy status
validate MODEL_ID Validates one stored artifact: filesystem, size, integrity
compatibility MODEL_ID Compatibility evaluation without running anything
execute MODEL_ID "PROMPT" Run a prompt (recommended; strict evaluation applies)
run MODEL_ID --prompt "T" Legacy interface; no strict evaluation
chat MODEL_ID Interactive chat session with the model
serve HTTP API on 127.0.0.1 that executes models (see above)
runtime Resolved llama.cpp runtime state
detect System, CPU, memory and GPU
diagnose GPU software diagnosis (Vulkan/CUDA/ROCm)
verify Re-checks the GPU diagnosis, not artifact integrity
source huggingface REPO Inspects a remote source
search QUERY Queries the configured model discovery/catalog capability
inspect REPO Inspects one remote repository's declared variants and artifacts
plan REPO FILENAME Inspects one specific remote artifact

import PATH copies a local GGUF file into the model store. It reports the artifact's content ID (the SHA-256 CastleArq computed, which is the file's physical identity) separately from its logical identity, which stays UNKNOWN: a local file carries no evidence of which model it is, of who published it, or of its integrity declaration. Only general.architecture is read, as physical GGUF evidence. Use --label NAME to choose the storage and presentation label; the store sanitizes it, and it is never used as a model id. Importing does not run anything: run the artifact later with execute.

detect, runtime, models, list, store, compatibility, source, search, inspect and plan are read-only: they change nothing.

search QUERY queries the configured model discovery/catalog capability and prints the remote candidates it returned, together with the next_cursor the provider produced when more results exist:

castlearq search "qwen coder"
castlearq search "qwen coder" --limit 50
castlearq search "qwen coder" --cursor "<next_cursor from the previous call>"
castlearq search "qwen coder" --json

It reports candidates as the discovery provider declared them. It does not rank them, recommend one, score them against your hardware or select a quantization: choosing the artifact is a separate decision made by download, compatibility and execute. --limit is forwarded unchanged to the provider, which owns the bound. --cursor takes the opaque next_cursor from a previous call and forwards it unchanged; CastleArq never decodes or interprets it, and it never paginates automatically. Results are remote, unverified metadata: they say what a source declares, not what your machine can run.

verify checks environment remediation after a diagnose. It is not an artifact integrity check; for that, use validate, which reports what can be proven about one stored artifact and which evidence is missing. list shows the derived state of every stored artifact.

Nine of these commands also accept --json for machine-readable output; see Machine-readable CLI output.

Machine-readable CLI output

Nine commands also accept --json, which prints exactly one JSON document on stdout instead of the human report:

compatibility   validate   list   store   import
models          runtime    detect plan

Everything else is unchanged: the exit codes are the same in both modes, warnings and notices (such as the legacy-store notice) go to stderr, and argparse errors stay plain stderr + exit 2 with no JSON at all. The document is always this envelope:

{
  "schema": "castlearq.cli",
  "schema_version": 1,
  "command": "compatibility",
  "exit_code": 0,
  "payload": {},
  "warnings": [],
  "error": null
}

exit_code is the code the process really returns, warnings is a list of strings, and error is either null or a {"kind", "message"} object. A --json run and a human run of the same command always agree on the exit code.

Two rules keep this output unambiguous for scripts:

  • UNKNOWN is explicit, never a string. A property that is relevant but was not observed is reported as {"value": null, "status": "unknown", "reason": "not_observed"} (other ratified reasons are no_checksum_declared, no_size_declared, no_catalog_evidence and not_declared). UNKNOWN is never FAILED, never a bare null that hides its status, and never the literal "Unknown".
  • Identity and integrity stay separate. import reports content_id, the SHA-256 CastleArq computed for the bytes it copied. That is the file's physical identity, not an integrity declaration: the imported artifact declares no checksum, so its integrity stays UNKNOWN (reason: "not_declared"). Its logical_identity stays UNKNOWN too (reason: "no_catalog_evidence") — the label is addressing and presentation, never a model id.

In compatibility --json the strict evaluation and the admission projection are two separate objects (payload.evaluation and payload.admission). An evaluation that is INSUFFICIENT_EVIDENCE while admission still permits execution is observable as exactly that, and is reported truthfully in both modes. An operational failure is error.kind = "evaluation_error" with exit 1; an admission denial is not an error, it stays in the payload.

models reports its catalog assessment under legacy_compatibility, which is the historical, hardware-scored domain and not the strict evaluation domain. plan reports the download planner's own statuses (ready, already_downloaded, blocked, unknown); an UNKNOWN plan is a plan status, not an error.

The commands diagnose, verify, execute, run, download and source do not accept --json and reject it with exit 2; serve and chat are outside this contract by nature.

Chat

castlearq chat qwen2.5-coder-7b-instruct

Opens an interactive session with the model already loaded. During the session it responds to /regen (regenerate), /clear (clear history), /read <file> and /glob <pattern>; /exit or Ctrl+C closes it.

chat uses the same runtime and the same local artifact as execute, so a model downloaded with download is reused without downloading it again. To check compatibility before starting a conversation, run castlearq compatibility MODEL_ID.

Opening a chat session starts a model, so it is subject to the same admission as execute.

Architecture

Technical architecture, contracts and decision records are in docs/, covering runtime discovery, capability, compatibility, admission, the model store and execution. It is optional material for the user flow above.

Development

From a checkout, the supported mechanism is:

python3 -m castlearq.main --help
python3 -m castlearq.main --version

Tests run with pytest:

python3 -m pytest

pytest is not a runtime dependency. It is declared as a pinned development extra, which is what CI installs:

python3 -m pip install ".[dev]"

The same command runs on every push to main and on every pull request, across Python 3.11, 3.12 and 3.13. A red run is a validation failure: it is diagnosed, not worked around. The suite needs no llama.cpp, no models and no GPU; tests that open a socket do so on 127.0.0.1 only. Working from a checkout is not required to use the installed package.

CastleArq is developed by Nicolás Bruna.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.

Metadata

Release files for castlearq 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for castlearq 0.5.1
File Size Uploaded Provenance Actions
castlearq-0.5.1.tar.gz 546.8 kB With provenance Details for castlearq-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for castlearq 0.5.1
File Interpreter ABI Platform Actions
castlearq-0.5.1-py3-none-any.whl Python 3 none any Details for castlearq-0.5.1-py3-none-any.whl

Total release size: 846.0 kB

Release files / castlearq-0.5.1.tar.gz

Download URL castlearq-0.5.1.tar.gz
Size 546.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7dd9f6b6d6767a6333943b75440e3fb83703878cb1a8a759fc0a9d6bf134ecc8
BLAKE2b-256 checksum
How to use checksums
d70d51072fd6f95815d3401a27e7c964414c301c9cb6615059cfdedab014ad4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / castlearq-0.5.1-py3-none-any.whl

Download URL castlearq-0.5.1-py3-none-any.whl
Size 299.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ee8b43eb9a6beaf35355612c24c85a8ebdabb881737e67185bba4f72add17596
BLAKE2b-256 checksum
How to use checksums
019f47c1fa1044fe15e941ab267a103e111da6add2694eb3a1d120637f7c7701
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Security for castlearq 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for castlearq-0.5.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page