User Guide

Install

npx localsutra-ai doctor              # no install
npm install -g localsutra-ai          # optional; gives `localsutra`
localsutra --version

1. See your hardware

localsutra doctor                     # JSON
localsutra doctor --format md         # readable
localsutra doctor --out my-pc         # writes my-pc.json, .md, .html

GPU shows unknown unless nvidia-smi is available. That means "not determined", not "no GPU".

2. Will a model fit?

Create a catalog (see fixtures/model-catalog.json):

{"models":[{"id":"my-7b-q4","parametersB":7,"bitsPerWeight":4,"contextTokens":4096,"kvBytesPerToken":131072}]}
localsutra fit --catalog catalog.json --format md

Read possibly_fits as "memory looks plausible", never as "it will run". Provide kvBytesPerToken for a closer estimate. Check the runtime's own documentation too.

3. Check a local runtime

localsutra probe --runtime ollama          # http://127.0.0.1:11434/
localsutra probe --runtime llama --endpoint http://127.0.0.1:8080/

responding only means the service answered. Failure codes tell you why (unreachable, timeout, ...).

4. Time a model you already installed (opt-in)

localsutra infer --model llama3.2:3b --runs 3

Run 1 includes model loading (cold); later runs are warm. Tokens per second appear only if Ollama reported counters. Your prompt is hashed, never saved; output is discarded.

5. Benchmark honesty

localsutra benchmark runs a CPU loop. It is not an AI benchmark. Use compare only on reports from the same machine and settings.

6. Run the audit

localsutra audit --out my-audit

Open my-audit/audit-report.html. Verdict meanings: APPROVED_WITH_EVIDENCE, REVIEW_REQUIRED, BLOCKED_UNSAFE. Read the "Not tested" section.

7. Verify a report

localsutra verify --report my-audit/audit-report.json

Exit code 1 means the content changed after sealing.

8. Use the skills with your coding agent

localsutra install-skills --project . --ide claude --dry-run
localsutra install-skills --project . --ide claude

Then ask your agent to use localsutra-prime. Skills never grant permissions by themselves.

Troubleshooting

SymptomCause / fix
Non-loopback runtime endpoint blockeduse http://127.0.0.1:PORT/
EEXIST when writing a reportfile exists; choose another --out or add --force
probe says unreachablestart Ollama or llama-server; check the port
GPU unknowninstall NVIDIA drivers or accept unknown; other vendors are not probed yet
Windows: symlink errors in testsnot an issue for users; tests use junctions

Privacy tips

Reports contain your CPU model, RAM, disk size and model names. Review before posting them in public issues.