Using it from the command line
On this page
- Step 1. How to run anything
- Step 2. Where to run it from
- Step 3. Connect a repository
- Step 4. Use it
- Find code by meaning
- Walk from a symbol
- Ask about files you already know
- Triage a log
- Read an image, translate a document
- Look at the state of things
- Estimate capacity on the target computer
- Prepare and verify transferred offline materials
- Plan the offline environment and its known disk budget
- Apply a bundled dependency or import model artifacts
- Execute selected offline steps with a durable journal
- Install pinned SCIP packages from an offline npm cache
- When something refuses
Step 1. How to run anything
Everything goes through the launcher — the stable entry point that does not move when the
product updates. The version directory under bin\versions\ changes with every release, so
never write a path into it, neither in a script nor in a client:
& "$env:LOCALAPPDATA\LocalAi\bin\launcher\localai-launcher.exe" run <command>
To stop repeating that, make an alias for the session:
function lai { & "$env:LOCALAPPDATA\LocalAi\bin\launcher\localai-launcher.exe" run @args }
The examples below use lai <command>.
Step 2. Where to run it from
From anywhere. Commands that work on a repository take --root:
lai localai repo status --root C:\work\myapp
With no --root, the repository containing the current directory is used. So this works too:
cd C:\work\myapp
lai localai repo status
A worktree is the same repository. A repository is identified by its shared git
directory, so all of its worktrees, Claude, Codex and the command line see one index. But for
a build, point --root at the tree you are editing: an overlay is built for one exact
state of the files.
Step 3. Connect a repository
Indexing is opt-in per repository. Until you ask, nothing is read.
lai localai repo status --root C:\work\myapp
NOT_CONFIGURED: C:\WORK\MYAPP\.GIT — offer CodeSearch, LocalLm, shared broker, mainline generations, branch overlays, hooks, Claude MCP and Codex MCP.
Connect it and install the hooks:
lai localai sync --root C:\work\myapp
lai localai hooks install --root C:\work\myapp
The first build reads the repository and reports the current indexing pass.
localai repo status --follow shows the phase, origin operation GUID, requested/current
worktree and completed/total passes. When available, chunk counts, rate and ETA describe
the current pass; whole-operation chunk totals, rate and ETA stay unknown.
Use the displayed origin GUID to request cooperative cancellation:
localai sync cancel --root <root> --operation <GUID>.
A different GUID is refused. A cancellation request does not prove that work has stopped;
keep observing status. An MCP wait timeout also leaves backend state unknown.
From then on the hooks keep the index current by themselves: after a commit, checkout, merge or rebase. Hooks you already had are not overwritten — Local AI joins the chain and calls them first.
Check:
lai codesearch status --root C:\work\myapp
Step 4. Use it
The full list of commands is in the What the command line gets table. Here is what they look like in use.
Find code by meaning
lai codesearch search --query "who is subscribed to a broker job finishing" --top 3
What it printed on 2026-09-06; line numbers and scores move as the code changes:
src\LocalAi.Broker.Core\DurableQueue.cs:1318-1323 [Method] cos=0.616
IBrokerQueue.CompleteAsync
Task CompleteAsync( Guid jobId, string workerId, Guid leaseId, JsonElement body, …)
chunk_id: cs1.AUAwZWNjOTAx…
src\LocalAi.Contracts\LocalRunObserver.cs:27-27 [Type] cos=0.604
BrokerJobPending
public sealed record BrokerJobPending(bool Running): LocalRunStep
chunk_id: cs1.AUAwZWNjOTAx…
The word “subscribe” appears nowhere in the code that was found — it matched by meaning.
cos is how close; chunk_id goes to codesearch get-chunk to pull the fragment in full:
lai codesearch get-chunk --id cs1.AUAwZWNjOTAx…
Walk from a symbol
Once you have a place, keep going with navigation rather than another search. Lines and
columns count from one — exactly as search prints them and an editor shows them. Use the
current start line from your search result; the examples below use line 346 for CompleteAsync:
lai localai semantic references --path src/LocalAi.Broker.Core/DurableQueue.cs --line 346 --column 1
lai localai semantic implementations --path src/LocalAi.Broker.Core/DurableQueue.cs --line 346 --column 1
Ask about files you already know
lai localai ask "List the public members of this class, one per line." src/CodeSearch.Core/Chunking/GenericTextChunker.cs
For extraction/classification, opt into a checked flat JSON object with
--profile Extraction (or Classification) and --schema contract.json.
MCP ask_local accepts the same JSON as the optional outputSchema string.
For example, classify a supplied issue into bug or question with this contract:
{"schemaVersion":1,"fields":[{"name":"label","type":"String","allowedValues":["bug","question"]}]}
lai localai ask "Classify this issue." issue.txt --profile Classification --schema contract.json --json
Version 1 is a bounded flat-object contract, not general JSON Schema: up to 64
case-sensitive fields, String, Integer (signed Int64), Number, or Boolean;
required defaults to true, allowedValues is an exact string enum. Nested values,
nulls, extra/duplicate fields, code fences and extra prose fail validation. The schema
is limited to 32,768 characters and the response to 1,048,576 characters. Unknown
schema keywords are rejected before inference. Cancellation is preserved.
The broker checks each attempt, including fallback. With --json, success adds
data.validation, and a rejected result exits 65 with error.code=result_rejected and
error.validation and no answer data. Without --json, success prints validation: <status>
on stderr, and a rejected result exits 65, prints result_rejected: with the validation on
stderr and nothing on stdout. MCP returns {answer,validation} inside its untrusted-content
boundary. Statuses are Valid, Empty, InvalidJson, SchemaMismatch; only Valid
carries a parsed value. Rejected output earns no cloud-token savings estimate.
Valid means the structure matches, not that the classification or extracted facts
are correct: check them against the supplied source. Without a schema, legacy
CLI/MCP output is unchanged and the broker records NotRequested. This opt-in feature
requires an updated broker as well as the client. Full translation retains its own
validator; a broker success does not replace it.
The model’s answer is written to stdout. A separate usage notice on stderr identifies the
call and the models actually used, reports elapsed time, and shows one approximate token
saving (or additional overhead). The underlying INPUT and OUTPUT values remain in the report.
Runtime calls use the versioned request-context comparison runtime-request-context-v2,
not account billing. INPUT compares the explicitly supplied task input, after selection and
truncation, with the arguments and model-visible response. Local output earns no assumed
cloud-generation credit; OUTPUT accounts only for generating the tool request. Either
difference can be negative; an unsuccessful, invalid or undelivered result earns no savings
estimate. A later cloud answer and transport framing outside that payload
are excluded from both sides. In methodology cloud-comparison-v2, MCP counts the tool name
and arguments as JSON, decoded result text (including the usage notice), and structured result
JSON, separated by newlines. JSON uses literal Unicode rather than transport escape sequences.
Hidden _meta in requests and results is excluded. Transport byte/character volumes still
measure the complete serialized result, including metadata. Non-text result blocks make the
response token estimate unknown; their encoded bytes are not treated as text tokens.
CLI counts serialized arguments and stdout followed by stderr, including the usage notice.
These representations are explicit proxies, not a measurement of a client’s model context:
client-specific framing and deduplication of text/structured results are unknown.
Text uses the bundled microsoft-ml-tokenizers-2.0.0:o200k_base vocabulary, checked against
independent reference counts. Images use openai-gpt-4o-tiles-v1 at high detail; PDF comparisons
use the rendered page images, not a provider’s native PDF upload. Neither profile claims to
match the cloud model used by your account. Duplicate source units within a call count once;
triage counts unique fragment text without overlap. Different unlocated slices or alternative
image/text representations of one source make the baseline unknown instead of double-counting.
Code and document retrieval do not establish how much source the cloud would have needed:
their notice reports the observed request/response context and unknown savings. Reading a
whole file for its hash or a search hit never earns whole-file credit. Missing evidence remains unknown with a reason;
administrative operations and code-only translation report not applicable.
The default is Unknown: the tool cannot infer the cloud context’s history. Pass NotPresent
explicitly only when the supplied task context has not entered the cloud context.
History and relevance are independent. A first-read text/image baseline additionally requires
contextBasis: "ExplicitTaskInput", _meta: {"localai/contextBasis":"ExplicitTaskInput"},
or CLI LOCALAI_CONTEXT_BASIS=ExplicitTaskInput. This is the caller’s assertion that the
bounded input was selected as necessary for this task, not an automatically proven minimum.
Do not set it merely because a file was opened or supplied. The default basis is Unknown;
undeclared context, retrieval and conflicting source coverage cannot earn positive credit.
For an already read source, pass sourceContext: "AlreadyPresent" to the supported MCP tool,
or _meta: {"localai/sourceContext":"AlreadyPresent"} on the request. Use "Unknown" if
context presence cannot be established. CLI uses LOCALAI_SOURCE_CONTEXT with the same values.
There is no cross-call context ledger: callers must supply this information on repeated reads.
Only counts, profile IDs and the scenario are persisted, never source/answer text. CLI response
capture is bounded to 8 Mi characters per stream; exceeding it makes the response token count
unknown. Existing JSON fields remain compatible; the canonical usage report and notice carry
this comparison, while older task-specific scalar estimates retain their legacy meaning.
Evidence is bounded to 16,384 distinct source units per call; longer streams report
source_evidence_limit instead of crediting a partial baseline.
Triage a log
lai localai triage build.log --question "why did the build fail"
Reads a log file of any length. It goes through the models the routing catalog names for log
triage in route order — candidates, then fallbacks — and for each installed one trial-loads its
context sizes from largest to smallest, up to the limit in log-triage.json, until the broker
accepts a load (by default, only when the model loads entirely into video memory). It then
works through the file in pieces sized to the accepted context.
The requested --question stays in fragment and reduction prompts and can ask for a summary
of successful operations. Default full-log triage retains its declared whole-source
comparison baseline. A custom question has an unknown task-context baseline: processing
the whole log does not establish the context needed for that question. The caller’s
sourceContext declaration is preserved.
For diagnostic triage, a streaming detector counts error diagnostic lines and occurrences by code independently of the model; repeated source lines are not deduplicated. MSBuild summary totals are reported separately. The report includes a source hash and original line numbers with bounded diagnostic and summary samples. Sample limits do not reduce counts; lines exceeding the parser limit explicitly mark the counts as potentially incomplete. Model-reported diagnostic counts are checked against the source. Incorrect counts, omitted errors or invented codes reject the model’s diagnostic inventory and produce the deterministic source report. No recognized diagnostics does not mean that the build succeeded.
For a custom question, compiler map/reduce prompts request an envelope with inventory
and requestedAnswer. Default triage without a custom question retains the original
three-field inventory object without an outer envelope.
The strict three-field contract, source reconciliation, repair and deterministic rendering
apply only to the nested inventory; source verification remains required.
The requested answer is displayed separately, labelled model-generated and not verified as
compiler evidence. An inventory validation pass does not verify that answer. A missing or
invalid answer is explicitly marked unavailable. Repair fixes only inventory without
replacing requestedAnswer.
One enclosing JSON code fence may be removed, followed by the same source reconciliation. A malformed inventory can receive at most one bounded format retry through the broker, using compact source counts and the already accepted model/context. Incorrect semantic counts are not repaired into a success. Cancellation stops the retry; a failed or oversized repair keeps the deterministic source report. Verification metadata records normalization, repair attempts, initial reasons and any repair failure. A failed job without a receipt explicitly marks its repair timings incomplete; the known queue/execution subtotal is not a complete retry timing.
It takes a stream too, so the log need not be saved at all:
dotnet build 2>&1 | lai localai triage -
Read an image, translate a document
lai localai read-image "What error is on this screenshot, and in which window?" C:\shots\error.png
lai localai translate --in docs\notes.md --from Russian --to English --markdown --out docs\notes.en.md
read_image and localai read-image also accept one PDF, up to 256 MiB.
Pass its path without other files and without --together. Pages are rendered
and sent to the model one at a time. In OCR mode, each page’s reading is returned
in full, in source order, under a numbered page heading. Other modes merge the
page answers. The console reports the current page and total; the final notice
names the file and the number of pages read. PDFs have no eight-page limit.
Use --pages "1,3-5" (MCP: pages: "1,3-5") to read selected PDF pages.
Numbers start at one and ranges include both ends. Pages are processed in document
order without duplicates, keeping their original numbers in headings and progress.
Only selected pages are rendered. Invalid ranges or numbers beyond the document
are refused before calling a model. Omit the option to read every page.
lai localai read-image "Transcribe the text" manual.pdf --profile Ocr --pages "1,3-5"
For PDF OCR, add --out transcript.txt (MCP: outPath) to save the complete UTF-8
transcript and receive a short file pointer. The output directory must already
exist. An existing output file is replaced atomically after every selected page
finishes; errors or cancellation keep the old file. The source PDF cannot be the
output. Nothing is silently shortened or returned inline on a write failure.
File contents remain untrusted data. Without an output path, OCR returns the
transcript inline as before.
Add --checkpoint ocr-progress (MCP: checkpointDirectory) to resume PDF OCR.
Repeat the same request after a stop: completed pages are loaded from disk without
rendering or calling a model again; only unfinished pages are processed. A fully
completed session can publish the transcript to another output file without inference.
The checkpoint contains page text and receipts, and allows only one active writer.
Use an empty directory for a new session and keep the output file outside it.
Changes to PDF bytes, selected pages, question, language, model override, routing
catalog or processor build are refused; use a new directory for those requests.
Each checkpoint record is limited to 4 MiB; oversized records fail without truncation.
lai localai read-image "Transcribe the text" manual.pdf --profile Ocr --checkpoint ocr-progress --out transcript.txt
Pages are rendered at up to 150 DPI, with at most 4 million pixels per page. Encrypted or malformed PDFs report an error with the file path; password input is not supported.
See the PDF parser and OCR measurements for separate text-layer, damaged-document and raster-limit checks, plus the limits of that evidence.
Document search indexes PDF, TXT, Markdown (.md, .markdown) and DOCX. Keep the index
outside the source folder; only supported files directly in that folder are included.
PDFs still use OCR by default. Other supported formats are read directly without a model.
lai localai documents index --source C:\Documents\Scans --index C:\Documents\SearchIndex
lai localai documents index --source C:\Documents\Text --index C:\Documents\TextIndex --pdf-mode TextLayer
lai localai documents search --index C:\Documents\SearchIndex --query "invoice number" --limit 10 --json
MCP equivalents are index_documents(sourceDirectory, indexDirectory, model?, pdfMode?) and
search_documents(indexDirectory, query, limit?, sourceContext?). Search finds a
case-insensitive literal phrase, returns at most one excerpt per source unit, and makes no
model call. Every PDF hit identifies the file, its SHA-256 version, one-based page,
normalized whole-page region (0,0,1,1), extraction kind and source excerpt.
OCR hits also name the extraction model and mark transcription accuracy unverified.
ocrOffset, matchLength and textOffset count UTF-16 code units in the page’s OCR
text; they are not coordinates of words in the PDF. No paraphrases or generated answers
are mixed with that text. OCR can misread or omit text; a missing match proves only
that the phrase was absent from the indexed OCR.
Explicit --pdf-mode TextLayer (MCP pdfMode: "TextLayer") reads embedded PDF text
with PdfPig 0.1.16. It never falls back to OCR: pages with no extracted text are
listed in the index result’s emptyPages; reindex with --pdf-mode Ocr to recognize
page images. Embedded text can contain hidden characters or a different reading order.
For these formats, textKind distinguishes ocr, pdf-text and plain-text; textVerification is
unverified, layout-unverified or source-text respectively. Text-layer extraction
does not claim a match to the visible page.
TXT/Markdown hits have null page, region, model and ocrOffset; their one-based
startLine/endLine describe the excerpt and matchStartLine/matchEndLine describe
the match. matchOffset, textOffset and matchLength count UTF-16 code units in the
decoded text file or extracted PDF page. Text is preserved, including line endings;
UTF-8 and BOM-marked UTF-16/UTF-32 are supported. Invalid encodings and NUL-containing
input are refused. Plain-text search returns at most one excerpt per file.
DOCX search reads main-body paragraphs and paragraphs in top-level table cells.
It joins adjacent text runs, preserves tabs and explicit breaks, and returns at most
one excerpt per paragraph. textKind: "docx-text" and textVerification: "layout-unverified"
identify this extraction. Each hit’s docxSource contains the declared main part,
namespaceUri for the w XPath prefix, and an exact xpath. One-based paragraph
counts direct paragraphs in the body or cell; table, row and cell count direct
XML siblings and are null for body paragraphs. Merged-cell positions describe XML,
not visual grid columns. File SHA-256 pins these references to that version.
page, region, model, ocrOffset and line fields are null. UTF-16 offsets refer
to the extracted paragraph. Pages, numbering, styles, hidden text and reading order
are not rendered or verified; text from hidden runs can be present.
DOCX extraction is deliberately partial. A paragraph containing unsupported inline
content (such as fields, drawings, notes or tracked revisions) is omitted in full
to prevent false phrase matches across a skipped fragment. Unsupported blocks,
content controls and nested tables are omitted. Header/footer, note, comment, style,
media and other unindexed package parts are listed in extractionNotices, with exact
part names and structural locations where available. External relationships are
reported and never fetched; hyperlink display text can still be read. Notices are
limited to 64 per file; additionalNotices counts the remainder across files.
Both index and search return notices, including searches with no hits. Search includes
notices only for sources that still pass its freshness checks. No match does not prove
the phrase is absent from the complete Word document.
Repeat documents index to refresh. Unchanged documents are reused; changed documents
are re-read and deleted entries disappear. Changing PDF mode invalidates extraction
reuse. Version-one and version-two indexes remain searchable; refresh atomically upgrades storage
to version three. The CLI/MCP response schema remains version one with additive fields;
indexSchemaVersion names the stored format. Search checks file hashes before returning
hits and reports changed, deleted or unreadable sources in excludedSources. Refresh
after changes; newly added files become searchable after that refresh. Publication is
atomic and cancellation keeps the previous snapshot; interrupted new OCR work is
repeated on the next run. Stored text remains local in snapshot.json. Its page hashes
detect accidental corruption, not deliberate tampering by someone able to rewrite it.
Pilot limits: 32 files, 128 pages per PDF, 256 MiB per PDF, 8 MiB per other file, 1 GiB
in total, 64,000 extracted characters per PDF page and 8 million in the index.
Results contain at most 2,000 characters
per excerpt and accept a 1–256-character phrase. Indexing reports token savings as not
applicable. Search compares only the source units represented in returned hits with the
complete tool request/response; this conditional estimate can be negative and is not
account usage. It does not count the entire corpus or replay earlier OCR usage.
DOCX additionally allows up to 256 archive entries, 8 MiB per expanded part,
32 MiB total declared expansion, 4096 direct body/cell paragraphs and 64,000 characters
per extracted paragraph. Consumed XML is also bounded by actual bytes, 100,000 reader
nodes and depth 64 per part. DTDs, ambiguous/unsafe package paths and duplicate entries
are refused. No archive content is written to source paths. Index summary pages counts
PDF pages; paragraphs counts extracted DOCX paragraphs, and docxDocuments counts DOCX files.
PDF parsing has cooperative cancellation between
pages, not a hard process deadline or memory sandbox.
Languages are given as names, not codes: --to Russian, not --to ru.
Translation checks reject copied source prose when the requested language names differ, including copies disguised by whitespace, punctuation or an appended attribution note. Each fragment is checked, so translating one fragment does not excuse copying another. Numeric literals must keep their spelling and order, including table cells and repeated values; decimal localization or reordering is conservatively refused. Fenced code is preserved separately, and model tags in generated attribution do not count as source numbers. Invalid output follows only the catalog’s fallback order; if no attempt passes, the tool returns an explicit failure and does not write the translated file. Rejected work retains its inference accounting and earns no successful translation credit. These are deterministic checks, not verification of meaning or target language. Unchanged names or words shared between languages can also be refused; same-language requests skip the copied-prose check. Code-only Markdown remains a no-model preservation operation. Documentation translations use the same unchanged-text and numeric checks.
For resumable translation, add --checkpoint translation-progress (MCP
translate_local: checkpointDirectory). Repeat the same request after cancellation
or a failed output write. Fragments passing structure and content checks are saved atomically and
reused; protected fenced code is copied unchanged. A fully cached result makes no model
call and does not replay old token counts or timings. Structural validation does not
certify the translation’s meaning or language.
Use an empty directory for a new session. Changes to input text, source/target languages, Markdown mode, routing catalog, processor build or UI language require a new directory. Checkpoint records contain translated text and receipts, are limited to 4 MiB each, and allow one writer at a time. Keep the output outside the checkpoint directory; aliases of the source or checkpoint files are refused. File output is published by atomic replacement, preserving the old file on cancellation or failure.
lai localai translate --in manual.md --from English --to Russian --markdown --checkpoint translation-progress --out manual.ru.md
With --markdown, a document containing only fenced code blocks and whitespace is
returned unchanged without calling a model or adding a translation note. Local token
usage is zero; cloud token savings are not applicable. In --json, this successful
result has reason: "no_translatable_text", modelCalls: 0, and null for the model,
residency, and both cloud savings estimates. Results that use a model keep their existing fields.
Look at the state of things
lai localai repo status --root C:\work\myapp # is the repository connected
lai codesearch status --root C:\work\myapp # where the index is, whether the mainline has moved past it
lai localai model status # which models are installed and resident
lai localai policy show # residency and update policy
lai localai telemetry # a summary of local jobs
lai localai doctor # what is wrong with the installation
lai localai diagnostics displays the complete diagnostic manifest and projected data without
saving a bundle. lai localai diagnostics --out C:\support\localai.zip saves those same contents
as a ZIP in an existing folder; it refuses to replace an existing destination. Add --json for
the existing machine envelope with saved, manifest and contents fields. Help, cancellation
and the administrative cloud-token report apply; collecting a bundle calls no model or network
service. Collection does not modify its sources; the usual CLI usage report is still recorded.
No new MCP tool or changes to existing MCP responses are introduced by this pilot.
The ZIP contains manifest.json and five JSON projections: collector/.NET/OS versions and the
recorded installed release, active queue state counts, recorded repository/index build states,
recognized broker error categories, and aggregate metric status counts. Cloud INPUT and OUTPUT
remain separate; measured and estimated samples have separate minimum/maximum values, including
negative savings. Unknown and inapplicable values retain their own counts. There is no summed
savings claim across calls or workflows. The current diagnostics call finishes after collection
and therefore is not included in its own snapshot.
Prompts, documents, answers, raw logs, exception messages, paths, repository/model names,
job/call IDs, settings and environment variables are excluded. There is no include-content
option. Repository ordinals identify entries only within this snapshot. The collector commit
and active version directory are installation version identifiers, not job/call IDs. These
records do not prove current service health or index freshness: files are read independently,
with capture timestamps and explicit missing/unreadable/invalid/linked/limited source counts.
Links are not followed. The first pilot samples at most 1,024 active jobs, 256 repositories,
2,048 retained usage reports, 1 MiB per source file (smaller bounds for states/reports), and
32 MiB of source bytes overall. Truncated samples are not necessarily the newest records.
The two broker log rotations contribute recognized categories only; unknown categories become
Other. Manifest file sizes and SHA-256 hashes describe the exact projected ZIP entries, not
the private source files. A cancelled or failed export does not publish a partial ZIP.
Estimate capacity on the target computer
localai hardware plan --release <folder> [--disk <existing-path>] [--json] verifies the release manifest’s signature and combines its model sizes with the current model-routing.json and residency policy. It estimates model/context combinations using fresh GPU capacity and available physical RAM measurements, with conservative memory reserves. Every combination requires preflight on this machine before use; existing or transferred residency proofs are ignored. The command loads no models, makes no network requests and changes no residency policy.
The release folder must contain compatible release-manifest.json and release-manifest.sig files signed by the embedded release key. The ZIP is not read or verified by this command. --disk selects an existing local directory; the default is LocalApplicationData. UNC/device paths and mapped network drives are rejected. The JSON envelope contains plan, catalogSource, policySource, dependencies and explanatory notices. Missing or corrupt policy files retain the strict default, with fileFound/fileUsed showing the source; an invalid configured catalog is refused. This administrative command reports cloud-token savings as not applicable.
Capacity uses the largest eligible single GPU, without summing adapters. The shared recommendation engine adds 1 GiB of runtime reserve and 256 KiB per context token to the signed base estimate. RAM is assessed conservatively against the same complete-model estimate. fits, exceeds and unknown are estimates; residencyProof is always preflight-required. Unknown hardware or unsigned model/context costs remain unknown. Disabled/Never catalog entries are excluded. Policy changes require the existing explicit localai policy set command.
Dependency checks establish executable presence on local PATH entries only; versions and usability remain unverified. The disk estimate is a lower bound covering recommended model downloads (once per model) and the package size recorded in the signed manifest. Unpacked runtime files, dependency installers, indexes and temporary-space reserves are not fully included. complete remains false even when the known minimum fits. Existing model files are not credited against downloads, and optional/manual models are listed without being included in the default disk total.
Prepare and verify transferred offline materials
lai localai offline bundle --source C:\prepared --out E:\localai-offline --json
lai localai offline verify --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --json
The source must contain release-manifest.json, release-manifest.sig, localai-package.zip,
and offline-components.json. The release signature is checked against the embedded release key;
the copied package’s length and SHA-256 must match that signed manifest. The ZIP is not extracted
or inspected here; the normal installer remains responsible for package-content verification.
Source and destination must be local, the output parent must exist, and the output folder must be
new. No downloads or bundled executables are started. Run these commands with the published
self-contained CLI; this transfer step does not need a global .NET SDK.
An example source inventory (replace the declared version and supply the actual file):
{
"schemaVersion": 1,
"components": [
{
"kind": "dependency",
"id": "dependency.ollama",
"version": "user-verified-version",
"files": ["dependencies/ollama/OllamaSetup.exe"]
}
]
}
kind is dependency, model or runtime. Dependency IDs come from the existing catalog:
dependency.git, dependency.ollama, dependency.github-cli, dependency.dotnet-sdk-10,
dependency.nodejs-20, dependency.scip-typescript, dependency.python-3-12, and
dependency.scip-python. A model ID is an exact enabled tag from the current model-routing.json.
A runtime component uses ID localai and the signed release version; it can list additional
runtime files, such as LocalAi.Installer.exe. The three signed release files are always included.
Every supplied component needs a version label and an explicit file list: no wildcards or recursive
folder expansion. Versions and component membership are declarations, not compatibility evidence.
Model artifacts must already be obtained through the normal authorized model workflow; this command
does not invoke Ollama, import a model store, or copy broker state/residency proofs automatically.
The bundle preserves relative paths and adds offline-manifest.json. Only declared files are copied;
all catalog dependencies and enabled models are listed as included or missing. Files shared by
components are copied/count once. transferredBytes counts listed materials; totalBundleBytes
also includes the inventory itself. These are transfer/storage lower bounds, not installed-space
requirements: expansion, SDK workloads, model import, indexes and temporary space are unaccounted.
Inventory limits are 8 MiB, 8,192 material files and 1 TiB total material bytes. Preparation publishes
by moving a completed staging folder; failures/cancellation do not publish a partial output.
Keep the reported manifestSha256 separately in a trusted location. The inventory is not a new
publisher signature: copying a hash alongside an altered inventory would not establish trust.
offline verify first requires that independent hash, then checks every file and the signed runtime
metadata/package hash. Missing, extra, modified or linked files, unsafe paths and case collisions
are refused. Verification reflects the bytes observed during that invocation; it does not authorize
later execution of a changed file. Both commands use the standard JSON envelope and administrative
cloud INPUT/OUTPUT reporting (not applicable).
Missing components stay explicit even when integrity verification succeeds. completeForInstallation
remains false and installationState remains installation-unverified. Clean-machine/no-network
acceptance is still pending in #612.
These commands establish a reproducible transfer inventory and byte integrity, not a fully installable
or usable offline environment.
Plan the offline environment and its known disk budget
lai localai offline plan --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --disk C:\prepared --json
This read-only command re-verifies the bundle and lists the sequence: catalog dependencies, the
normal runtime installer, model import, separate Ollama root configuration and broker preflight.
All dependencies and enabled models in the current catalog are accounted for, including missing
inventory rows; this is catalog coverage, not a recommendation to install every optional component.
Installed dependency versions are not detected. Included dependency recipes and the model graph
use the same validators as the individual application commands. Unsupported recipes and invalid
model graphs remain explicit; planning never launches an installer or model, copies model files,
changes configuration, or applies the sequence. --mode apply is not supported here.
--disk must name an existing local directory without links, junctions or mounted-directory
aliases. The disk report is a single-volume planning scenario, not a reservation or a cross-volume
installation check. The known budget separates runtime artifact bytes, ZIP expansion, unique model
files, the largest sequential dependency staging payload, retained npm materials and the two
copies of a bundled uninstaller. Archive expansion comes from the
trusted ZIP’s bounded central/local-header and layout checks shared with the normal installer;
it does not replace decompression, package-metadata verification or Authenticode validation.
The conservative known additional-space budget is:
runtime artifacts + unique model files
+ retained npm materials
+ 2 * bundled LocalAi.Installer.exe (when the runtime component lists it)
+ max(2 * compressed runtime package + runtime ZIP expansion,
runtime ZIP expansion + largest validated dependency staging payload)
The two compressed copies reserve the normal directory-feed/verifier preparation flow; the runtime
stage is additional to installed artifacts and stays retained while selected dependencies execute.
Model import publishes its copied stage by renaming it,
so shared blobs and the model stage are not counted twice. Existing bundle storage is reported by
offline bundle separately. Missing/invalid material sizes, dependency installed/temporary sizes,
old-version/launcher backups, indexes, caches and filesystem overhead remain explicit unknowns.
Below-budget free space yields below-known-budget; unavailable space yields unknown; enough
space still yields incomplete. readyForInstallation and disk complete remain false. A successful
JSON envelope means the plan was generated, not that the environment is ready. Selected execution
is available through offline execute below; clean-machine/no-network acceptance remains outstanding in #612. Cloud INPUT/OUTPUT
accounting is administrative (not applicable).
Apply a bundled dependency or import model artifacts
lai localai offline install-dependency --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --component dependency.ollama --json
lai localai offline import-models --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --out C:\localai-models --json
Both commands default to --mode plan; add --mode apply to execute the displayed operation.
Each invocation verifies the complete bundle again against the separately trusted inventory hash.
Use the published self-contained CLI. Both commands report administrative cloud INPUT/OUTPUT as
not applicable and do not invoke a model.
Dependency application requires offline-actions.json in the source and its explicit inclusion in
the runtime component’s files before building the bundle. For example:
{
"schemaVersion": 1,
"actions": [{
"component": "dependency.ollama",
"kind": "exe",
"installer": "dependencies/ollama/OllamaSetup.exe",
"arguments": []
}]
}
The empty argument list above is an interactive-launch example, not a verified unattended recipe.
Supply the vendor’s documented arguments for the exact full offline installer you prepared. The
installer and every companion file must belong to that dependency’s inventory entry and share one
directory with unique filenames. Nested payload directories are unsupported. Application runs one
EXE or MSI on Windows, after copying and hashing the selected files in a protected temporary folder
and retaining file handles against replacement throughout execution. MSI uses the system msiexec
with /i, /qn, /norestart; recipe arguments may only be uppercase PROPERTY=value entries.
There is no shell-script, package-manager or network fallback in the EXE/MSI command. Pinned SCIP
npm caches use the separate offline install-npm command below.
The inventory hash trusts the supplied recipe and bytes, not their publisher or declared version.
The external installer may access the network or make partial changes; network isolation, installed
version and usability are not established here, and Local AI cannot automatically roll changes back.
Installer exits 0, 3010 and 1641 produce state=completed; the latter two set rebootRequired=true.
Other failures return a nonzero CLI exit with ok=false while preserving result details. Cancellation
and timeout produce cancelled and timed-out. If termination cannot be confirmed, the state is
termination-unconfirmed; retainedDirectory identifies preserved installer files. Resolve the
process state before retrying or removing those files. The command does not elevate privileges.
Model components must list the complete Ollama schema-2 manifest/blob graph, rooted at
models/manifests/<host>/<namespace>/<model>/<tag> and models/blobs/sha256-<digest>. Config and layer
digests, sizes and inventory hashes must agree; extra files such as residency proofs are rejected.
Only enabled catalog tags are accepted. Short names default to registry.ollama.ai/library and
latest. This Windows path subset permits 1–80 ASCII letters, digits, underscores, dots and hyphens
per segment, starting with a letter, digit or underscore; host ports and digest-qualified tags are
unsupported. Action documents and individual model manifests are limited to 1 MiB each.
Import requires a new local output folder outside the bundle, with an existing parent. Verified
files are copied to staging and published by a directory move; existing stores are never merged
or replaced. OLLAMA_MODELS, the active runtime and policy are unchanged. Configure the Ollama
model root separately, then run the existing broker preflight on the target machine; backend/model
startup and residency proof are separate steps. The Windows wizard’s dependency flow is unchanged.
Clean-machine installation without network access or a preinstalled SDK remains an acceptance task.
Execute selected offline steps with a durable journal
lai localai offline execute --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --request C:\prepared\request.json --out C:\prepared\run-01 --json
The default --mode plan validates the selection without creating the run folder or applying
changes. Add --mode apply to execute it on Windows. Example request.json (at most 1 MiB):
{
"schemaVersion": 1,
"dependencies": ["dependency.ollama"],
"installRuntime": true,
"modelsOutput": "C:\\localai-models"
}
Choose only required EXE/MSI catalog dependencies. Schema 1 requests keep the original behavior;
use schema 2 and an explicit npm array to include npm components in the same journaled run.
For example, a request selecting only SCIP TypeScript is:
{
"schemaVersion": 2,
"dependencies": [],
"installRuntime": false,
"modelsOutput": null,
"npm": [{
"component": "dependency.scip-typescript",
"node": "C:\\Program Files\\nodejs\\node.exe",
"npmCli": "C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js",
"output": "C:\\localai-scip-typescript"
}]
}
Schema 2 makes older executors refuse the request instead of silently ignoring npm selections.
Node/npm must already exist when planning; this does not bootstrap a missing toolchain. Each npm
selection follows the pinned cache rules below and requires its own new prefix. Duplicate component
selections and overlapping run/model/npm destinations are refused before effects. The plan reports
dependencyOrder: selected EXE/MSI and npm components use catalog order regardless of array order,
then runtime and model steps follow. npm intent and outcomes use the same durable journal; failure
or uncertain termination prevents later steps, and retained files appear in steps[].retainedDirectory.
PATH setup is optional below; toolchain/functional compatibility remains a separate requirement.
To register the selected tools, use "schemaVersion": 3 and add "registerPaths": true to the
same request. At least one runtime or npm selection is required; older schemas reject this option.
The default is false, preserving existing requests. userPath in the plan shows the original
and proposed user PATH and the selected directories: the runtime launcher directory, each npm
selection’s Node directory and its node_modules/.bin. The Node executable must be named
node.exe. Literal directory names containing PATH delimiters, quotes, percent signs or line
breaks are refused. Existing entries keep their order; duplicate directories are not added.
The configuration:user-path step runs after all selected installations/imports succeed, with
durable intent before its effect. It checks that the directories and launcher/npm command shims
exist without links, checks that user PATH still equals the execution plan’s snapshot, appends
the missing entries and reads the stored value back. A detected concurrent change stops the step;
Windows registry updates are not an atomic compare-and-set. Failed writes/readback are reported
in steps[].detail, leave the step pending and never trigger a retry or rollback. PATH may already
have changed after a failed write/readback. Earlier installed files remain. Machine PATH and
existing process environments are unchanged. Start a new session before using the commands;
earlier PATH entries can still resolve a different Node/SCIP version. Compatibility and broker
preflight remain required, and readyForUse=false remains explicit.
To bind imported models to broker-managed Ollama launches, use "schemaVersion": 4 and
"configureModels": true, with a non-null modelsOutput. Runtime installation must be selected
or its destination root must already exist. The default is false; schemas 1–3 refuse this option.
The plan’s modelSetup names the imported directory, ollama-launch.json and the prior file hash.
After import, configuration:ollama-model-root discovers Ollama through the installer’s verified
installed-application probe (registry entry, approved directory and executable identity), never
through PATH. Its journal intent precedes the probe and the write. Missing/unverified Ollama,
a detected concurrent record change, a write error or a failed readback stops later steps with
the configuration still pending. Imported files remain. The record is published by a flushed
temporary-file rename; the before/after checks are not an atomic compare-and-set with other writers.
Schema 2 of ollama-launch.json stores the explicit model directory. On a future broker-managed
launch, the broker validates that this local directory exists without links and sets OLLAMA_MODELS
only in its child process. An unavailable directory prevents launch instead of falling back to the
default store. A later installer update preserves the configured directory. User/system
OLLAMA_MODELS and an already listening backend are unchanged. Use a runtime that supports this
record schema; older runtimes refuse it. Stop an existing Ollama backend deliberately before using
the configured launch, then run the existing model preflight through the target broker. This option
does not stop/start a backend, run inference or transfer residency proofs. A configured directory
does not establish model compatibility or readiness.
To add the Windows uninstall entry for the current user, use "schemaVersion": 4,
"registerUninstall": true and "installRuntime": true. The bundle’s runtime component must
explicitly include the release’s self-contained LocalAi.Installer.exe at the bundle root.
Its bytes and SHA-256 are covered by the independently trusted bundle pin. Before any dependency
runs, the file is copied into protected staging, rehashed and retained; applicable release
Authenticode requirements still apply. The plan’s uninstall section shows its hash, destination,
registry subkey and previous entry. An existing entry for another installation root is refused.
After runtime activation, configuration:uninstall records intent, copies the retained installer
to installer/uninstall/LocalAi.Installer.exe and registers Local AI Toolkit in the current user’s Windows
installed-app list. It opens no installer UI. Registry snapshot checks and registry/file readback
detect changes and failures; they are not an atomic transaction. Failure stops later steps, and
partial runtime, file or registry changes may remain without automatic rollback. Functional
uninstall acceptance is still required. The disk plan reserves both installer copies and retained
npm project/lock/cache files; installed npm trees, generated files and vendor temporary space remain
unknown, so it never claims complete disk readiness.
To check selected imported models on the target installation, use "schemaVersion": 5 and
"preflight": [{ "model": "<bundled-model-tag>", "contextTokens": 8192 }], replacing the placeholder
and context with a pair present in both the current catalog and signed release manifest. This option
requires installRuntime=true, configureModels=true and import of every selected model. Older request
schemas refuse it. Planning lists the selections without starting a process.
After import and model-root setup, each preflight:<model>:<context> step records intent, holds the
verified launcher and active-version lease, checks model status and requests broker preflight. A missing
model or a pending pull stops the sequence; this path never downloads a model. The target root is passed
explicitly to the shared broker, and the target residency policy is read without changing it. model status
and model preflight accept a final --runtime-root <dir> for this purpose; it must be an existing local
directory without links, given as an absolute path. The option is refused by model pull.
Successful steps record proof (model, context, catalog, model/VRAM bytes and verification time) and
residencyPolicy; rejected or invalid responses never become accepted proofs. Partial/CPU placement
is accepted only under the target policy. Failure stops later selections and PATH setup. The original
plan retains its pre-execution requirements; step proofs report what completed. Other model/context
pairs remain unchecked. An already running Ollama is not restarted: successful residency checks do not
prove which model source or directory it used. Source/directory verification, complete dependency/disk
evidence and clean-machine offline acceptance remain required; readyForUse=false is unchanged.
The command does not add optional components. An empty
dependency array, installRuntime=false or modelsOutput=null omits the corresponding steps, but
at least one step (including an npm selection) must remain. Dependencies run in catalog order, followed by runtime activation
and import of all included, enabled models. The dependency recipe and model rules above still apply.
Every supplied path must be local. Model and run outputs require new, separate folders with existing
parents, outside the bundle and runtime installation. Existing run folders are never resumed.
Before any dependency executes, a selected runtime passes the normal full signed-package, metadata
and applicable Authenticode verification in protected staging. Its verified files remain retained
through execution. Runtime activation uses the current user’s default Local AI installation and may
stop running tools and change the active version. PATH is changed only by the explicit schema-3
option above. Windows uninstall registration is optional as described above; other wizard settings remain separate.
Model-root setup is optional as described above; it does not change user/system OLLAMA_MODELS.
The run folder contains plan.json, journal-*.json and, when recording succeeds, result.json.
Each step’s intent is flushed before its effect. Failure, cancellation, timeout, reboot request,
unconfirmed process termination or a journal write failure prevents subsequent steps. Reboot and
uncertain outcomes leave an incomplete journal; uncertain effects remain Running. The result
preserves completed steps, pending identifiers, runtime outcome and retained dependency files in
steps[].retainedDirectory. Confirm process/installer state before retrying or deleting retained
files. There is no automatic replay, resume or rollback of the whole run; partial changes can remain.
recordingComplete=false means available records may be incomplete.
CLI exits are 0 for a plan or completed selected steps, 130 for cancellation, 75 for timeout or reboot,
74 for recording failure and 70 for failed/uncertain execution. Such nonzero results use ok=false
and retain the result details. Invalid requests use 2 or 65; an existing output uses 73.
Even state=applied reports readyForUse=false: dependency versions/prerequisites, complete disk
requirements and offline usability remain unverified. Select model-root setup and target preflight
explicitly or complete them separately. Only the selected preflight step invokes models; no residency
proof is transferred from the preparation machine. The command adds no network fallback or privilege elevation. External vendor installers can
still use the network. Cloud INPUT/OUTPUT accounting is administrative (not applicable).
Install pinned SCIP packages from an offline npm cache
lai localai offline install-npm --bundle E:\localai-offline --manifest-sha256 <trusted-hash> --component dependency.scip-typescript --node "C:\Program Files\nodejs\node.exe" --npm-cli "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" --out C:\localai-scip-typescript --json
The default is --mode plan; --mode apply installs on Windows into a new local prefix with an
existing parent, outside the bundle. Existing prefixes, global packages and PATH are preserved.
Supply existing local Node/npm paths explicitly; their provenance and versions are not verified
by this command. Node must be compatible with the selected package. This command invokes no models
and reports administrative cloud INPUT/OUTPUT as not applicable.
Only the current catalog’s pinned dependency.scip-typescript and dependency.scip-python packages
are supported. For each component, declare these files under its dependency inventory entry:
npm/<component-id>/package.json
npm/<component-id>/package-lock.json
npm/<component-id>/cache/_cacache/<every prepared cache file>
List each cache file explicitly; the inventory does not expand globs. Do not include node_modules,
logs or .npmrc. The component version must equal the catalog version. package.json allows only
name, version, private and dependencies; dependencies must contain exactly the selected package
at that exact version, without a range. For TypeScript the dependencies object is
{"@sourcegraph/scip-typescript":"0.4.0"}; for Python it is
{"@sourcegraph/scip-python":"0.6.6"}. Use a version-3 lockfile with matching root dependencies
and package version. Registry package entries require HTTPS registry.npmjs.org URLs and SHA-512
integrity values. Git/file links, workspaces and arbitrary package sets are unsupported.
Prepare the project and cache on a connected machine in a new folder, running Node’s npm-cli.js
with install --ignore-scripts --global=false --no-audit --no-fund --logs-max=0 --cache ./cache
--registry=https://registry.npmjs.org from that folder. Use the working directory, not --prefix,
for this preparation command. Include only the declared project, lock and cache files in the transferred bundle.
Application re-verifies the complete pinned bundle, copies selected materials into protected
staging, and runs npm ci --offline --ignore-scripts --global=false --no-audit --no-fund through
Node with a private cache, separate empty user/global configs and an explicit working directory.
Missing cache entries fail without an online fallback. On success, installed package name/version
are checked; Python receives the existing hash-pinned Windows compatibility patch. The completed
stage is published by moving it to the new prefix. Package commands are under node_modules/.bin;
PATH configuration and functional checks remain separate. The prefix also retains its private cache.
Failed/cancelled/timed-out npm runs retain staging for diagnosis. result.retainedDirectory names
it. termination-unconfirmed means npm may still be running; establish its state before retrying
or deleting files. No failure publishes the destination. readyForUse=false remains explicit even
after success. Offline flags are not a firewall test, cache availability is not functional acceptance,
and installed/temporary disk requirements remain incomplete. offline plan now recognizes these
materials and their staging bytes, while reporting the separate toolchain/prefix requirement.
The same operation can be selected in a schema-2 offline execute request and recorded in its journal.
When something refuses
A refusal is a message, not a breakage. Three common ones:
| What you see | What it means | What to do |
|---|---|---|
No overlay matches this worktree |
edits are saved, the index is behind | lai localai sync --root <repo> |
NOT_CONFIGURED |
the repository is not connected | lai localai sync --root <repo>, then hooks install |
The model backend is unavailable |
the model backend refused a batch; the build waits for it and goes on by itself | nothing, usually — if the build did stop, run lai localai sync --root <repo> again; what was computed is kept in a checkpoint |
← Using it with a cloud agent · Contents · What language it answers in →