# Preview managed local AI and OCR setup

Evaluate the managed LOCAL_AI provider and the unreleased managed OCR setup from a source build.

Canonical HTML: https://shafthq.github.io/docs/start/local-infrastructure/previews
Guide index: https://shafthq.github.io/llms.txt

# Preview managed local AI and OCR setup

These workflows are previews: each section states whether it is available on
`SHAFT_ENGINE` `main` or in a published release. Every install follows the shared [review and approve](/docs/start/local-infrastructure#review-and-approve-an-installation) flow; policy options and exit codes are in the [infrastructure reference](/docs/start/local-infrastructure/reference).

## Preview managed local AI

:::warning[Not in a published release yet]
The `LOCAL_AI` managed provider is available on `SHAFT_ENGINE` `main` after
[engine PR #4921](https://github.com/ShaftHQ/SHAFT_ENGINE/pull/4921). The
delivered merge commit is
[`a585b41980f78315aa353003ce5b5891f350a6a1`](https://github.com/ShaftHQ/SHAFT_ENGINE/commit/a585b41980f78315aa353003ce5b5891f350a6a1).
Use this workflow with a source build until a containing SHAFT release is
published.
:::

Use this profile when you want SHAFT to own a pinned `llama.cpp` runtime and a
reviewed GGUF model. You do not need a model manager, container, service,
endpoint, credential, administrator install, or machine-wide daemon. SHAFT
starts an authenticated loopback child process only when an approved AI request
needs it.

SHAFT continuously measures aggregate resident memory for the managed process
tree. If the tree exceeds 4 GiB, or its live memory inventory cannot be read
safely, SHAFT retires the session and returns the request's deterministic
fallback.

Start with explicit provisioning. Enable managed local processing, select the
manual compact candidate, and prevent an inference request from downloading
missing artifacts before you review the setup plan:

```properties title="src/main/resources/properties/custom.properties"
managedLocalAi.enabled=true
managedLocalAi.transparentProvisioning=false
managedLocalAi.model=qwen3-0.6b-q8_0
```

Run the shared review flow. Stop after `plan`, inspect both actions and the
printed digest, then install that exact plan:

 

The plan binds the exact runtime and model URL, version or revision, SHA-256,
license, and artifact size. Installation reports phase, completed bytes, total
bytes, and integer percentage on stderr, so `--json` output on stdout stays
machine-readable. An interrupted, failed, or cancelled operation returns no
receipt; fix the reported condition and retry the same still-current approved
plan.

Leave `--cache-root` and `--data-root` unset to use the effective managed-local
cache and the normal SHAFT data root. If you supply roots, pass both as absolute
paths on plan and install, and make `--cache-root` exactly equal to
`managedLocalAi.cacheDirectory`. SHAFT rejects a different cache instead of
provisioning files that inference will not use.

### Inspect readiness and privacy-safe diagnostics

Use `setup status` or `setup verify` for the two managed targets. Those
commands print `target readiness version detail`. Version is empty unless
READY. They report readiness/version/action, not the reviewed pin table.

Use `doctor local-ai-status` or MCP `doctor_managed_local_ai_status` for
enablement, eligibility, and the DISABLED snapshot. They do not list the reviewed pin table.

The MCP setup equivalents are `setup_status`, `setup_verify`, `setup_plan`,
and `setup_install`. IntelliJ uses those generic MCP setup tools instead of a
second lifecycle implementation.

The pin table on this page is the documented inventory. Setup commands do not
print revision, license, provenance, size, floors, update, cleanup, or
fallback. Diagnostics exclude absolute cache paths, filenames, checksums,
executable names, and exact host RAM, CPU, and free-disk values.

:::warning
Managed-local enablement grants local-processing consent only. It does not
grant remote or on-premises processing consent. The compact candidate failed
the current recommendation-quality gates, so use it only for manual evaluation
and keep deterministic SHAFT results authoritative. `managedLocalAi.enabled`
defaults to `false`. Do not flip that default to enable managed-local
automatically.
:::

### Inventory, defaults, and troubleshooting

The pin table on this page is the documented inventory. `setup status` and
`setup verify` print `target readiness version detail` even when the cache is
missing or the feature is still disabled. Version is empty unless READY.
Commands report readiness/version/action, not those pin-table fields:

| Field | Compact preview pin |
|---|---|
| Revision | runtime `b10400` / model `23749fefcc72300e3a2ad315e1317431b06b590a` |
| License | `MIT` / `Apache-2.0` |
| Provenance | `github.com/ggml-org/llama.cpp` and `huggingface.co/Qwen/Qwen3-0.6B-GGUF` |
| Size | platform runtime archive plus `639446688` model bytes |
| Storage | `SHAFT_USER_CACHE` — never an absolute cache path |
| Resources | compact floor `2` GB RAM, `2` CPUs, `3` GB free disk |
| Update | explicit reviewed plan; pin-bound; no silent float |
| Cleanup | owner-manifest only; unknown siblings preserved |
| Fallback | deterministic SHAFT result remains authoritative |

Release automation cannot float or silently replace model or runtime bytes. A
revoked or hash-mismatched artifact stays unpublished; the last good activation
remains active. An interrupted upgrade returns no receipt and does not activate
the new pair. Offline setup reuses a ready cache and never downloads or
substitutes a fallback URL.

Inspect readiness from each setup surface:

| Surface | Command |
|---|---|
| CLI | `shaft-cli setup status --profile LOCAL_AI --mode MANAGED` and `shaft-cli setup verify --profile LOCAL_AI --mode MANAGED` |
| MCP | `setup_status` and `setup_verify` |
| IntelliJ | the generic MCP setup tools; there is no second lifecycle |
| CI / headless | keep `managedLocalAi.enabled=false`; normal Maven never provisions or downloads; always pass `-Dallure.automaticallyOpen=false` |

`shaft-cli doctor local-ai-status` and `doctor_managed_local_ai_status` report
enablement, eligibility, and the DISABLED snapshot. They do not list the reviewed pin table.

If Maven or CI needs a local-AI assertion, run the unit tests that inspect
status, setup, cache, and properties. Do not add a `provision` or `benchmark`
step to a default pipeline. If a job must stay offline, pass `--offline` on
both `plan` and `install`; a missing or revoked pin fails closed.

### Clean, update, and roll back

Create and approve a separate plan for every maintenance operation. Clean
removes only unchanged installations owned by the current reviewed manifest;
changed, unknown, and other-version content is preserved. If changed or unknown
owned content blocks cleanup, the command returns a generic failure without a
receipt rather than listing each preserved installation:

```bash
shaft-cli setup plan \
 --profile LOCAL_AI \
 --mode MANAGED \
 --operation CLEAN \
 --output /absolute/path/local-ai-clean.json
shaft-cli setup install \
 --plan /absolute/path/local-ai-clean.json \
 --approve sha256: \
 --accept-license MIT \
 --accept-license Apache-2.0
```

Clean verifies the activation record and every selected installation before it
removes anything. If changed or unknown content blocks cleanup, SHAFT preserves
the verified active/previous record and its rollback candidate. After the
reviewed artifacts clean successfully, SHAFT clears the activation record, so
provision and activate two different reviewed pairs again before expecting
`ROLLBACK` planning to succeed.

For an update, create a new `INSTALL` plan from the current release and apply
it with `setup install` or its `setup update` alias. SHAFT provisions the new
content-addressed pair before activation and retains one exact prior reviewed
pair.

Rollback is available only after two different reviewed pairs have activated
successfully and the prior pair still verifies exactly. It swaps the cached
active and previous pairs without downloading or deleting artifacts:

```bash
shaft-cli setup plan \
 --profile LOCAL_AI \
 --mode MANAGED \
 --operation ROLLBACK \
 --output /absolute/path/local-ai-rollback.json
shaft-cli setup install \
 --plan /absolute/path/local-ai-rollback.json \
 --approve sha256: \
 --accept-license MIT \
 --accept-license Apache-2.0
```

SHAFT rechecks the approved candidate, complete owned file inventories, and
current host eligibility under the cache lock before changing activation. A
missing, changed, corrupt, or newly ineligible prior pair fails without a
rollback receipt.

## Preview: managed OCR setup

:::warning[Not released]
This workflow is not yet available on `SHAFT_ENGINE` `main` or in a published
SHAFT release. Keep using the [current OCR first-use model flow](../../integrations/ocr.md#configure-language-models)
until a release that contains the complete setup stack is available.

The preview defaults to the `eng` and `ara` model bundle. Omit `--language` to
use that bundle, or repeat exact Tesseract codes on plan and selected
status/verify commands. Install recovers the selected languages from the
reviewed plan:

```bash
shaft-cli setup plan --profile OCR --mode MANAGED \
 --language fra --language deu \
 --output /absolute/path/ocr-plan.json
shaft-cli setup install --plan /absolute/path/ocr-plan.json \
 --approve sha256: 
shaft-cli setup verify --profile OCR --language fra --language deu
```

The reviewed actions bind the normalized component set. Repeating `--language`
during install is optional and must match when supplied. The planned OCR
provider enforces `--offline`: it can accept a verified installed model, legacy
model, or artifact-cache entry without network access. It has no start, stop,
or logs lifecycle.
:::

## Related

- [Install SHAFT](/docs/start/installation)
- [shaft-cli command line](/docs/agentic/cli)
- [Programmatic properties configuration](/docs/reference/properties/Programmatic_Config)
- [Reporting](/docs/features/reporting)
- [Self-healing locators](/docs/reference/actions/GUI/Locators_And_Self_Healing)
- [BrowserStack](/docs/integrations/browserstack)
- [Local infrastructure overview](/docs/start/local-infrastructure)