AI and extensions setup

This guide describes the upcoming setup interface developed from Grid 0.66.5. It is not included in the published 0.66.5 desktop download.

Open File → AI & extensions, or search for AI & extensions in the command palette. The Grid Agent's AI setup button opens the same settings.

Connect an AI provider

Choose AI providers, then Add API key on OpenAI, Claude, or Vercel AI Gateway. Paste your key and choose Save and use. Grid selects the provider and clears the key field. Use provider switches between saved providers. Changing providers clears a custom model name; Model preferences lets you supply a name supported by that provider, or use its default. Choose Save model preference to keep a custom choice. Provider and model preferences are saved on the instance and restored after a restart.

Keys are encrypted on the Grid instance and are never stored in browser storage. Desktop sets up its private encryption secret automatically on first use. On a managed server, the administrator controls whether keys can be saved. Saving a key does not make a billable test request or certify that the provider accepts it. Choose Test connection & find models to verify access and load the provider's model list without generating text. Then choose a model under Model preferences. The check validates credentials and discovery; individual model access and account balance still govern generation.

Connect a model server

Under AI providers, choose Connect server on the Model server card. Enter the OpenAI-compatible API address shown by your server, such as http://localhost:1234/v1, and an API key only if it requires one. A server address without a path uses /v1. Local addresses refer to the computer running Grid; use an HTTPS address to reach another computer.

Choose Connect & find models, select a model, then Save and use server. If the server does not list models, enter the model name it exposes and save. Grid remembers the connection and model after a restart. Use server returns to that saved connection after you use another provider. Edit connection changes its address, model, or key. Leaving the key blank keeps a saved key for the same address; choose Remove saved key when saving to remove it. Changing the address clears the old credential and model from the draft.

The connection check lists models without generating an answer. Your server must support chat completions, and the selected model must support the images or Agent features you use. Hosted-provider keys are never reused for a model server. Grid does not start or install an external server; use Local models to download a model that runs inside Grid instead.

The saved provider or server becomes the default for Chat, Grid Agent, and new workbook AI_PROMPT and AI_ASK requests. One connection for Chat, Grid Agent, and workbook AI functions confirms that the runtime accepted your settings. If settings are saved but the runtime is unavailable, use Retry workbook connection after it is running. This requires the updated AI runtime. Managed Agent tasks can choose Use AI setup to use this same connection.

Your choice survives restarting either the app or its runtime. Existing completed workbook values remain until you rerun or change their requests. PREDICT formulas retain their exact selected model release. Instances with no saved selection continue using their existing runtime configuration.

Install a local model

In Grid desktop with the Pro AI runtime, choose Local models. Search for a model name or choose a family shortcut supplied by your selected registry. More families appear as you browse results, without needing another Grid update. Availability depends on that registry's published releases; preview entries cannot be installed.

Choose View. Grid verifies the signed model details and checks the actual runtime, available memory, supported formats, targets, and accelerators. The installation details show the compatible version, model download size, minimum memory, license, and limitations. Choose Install to download and verify it. The model download shows actual bytes and an estimated remaining time when there is enough transfer history. Pause download retains downloaded bytes; Resume download uses them after closing and reopening Grid. Servers that do not support resuming restart the transfer. Signed size and digest verification still apply to the complete file before installation. Metadata acquisition and final verification show their own activity status. Older bundled installers without progress events show an activity indicator instead.

Models that need companion or tokenizer files install them together with the weights. Grid verifies every file before making the complete model available. Grid shows the total download and free storage required, including temporary files. Find a good fit for this computer checks up to twelve displayed releases, prefers recommended memory headroom, and suggests a smaller compatible text model. Search for a family first to narrow those choices.

In 0.66.8, Help me choose for → Images and documents starts a vision-model search. You can refine it by family or model name. Find a good fit for this computer then recommends a compatible release whose signed package declares image input, using the same memory and storage checks. It never substitutes a text-only model when an image model cannot be found. You can also connect an image-capable hosted provider or model server in AI providers.

Details show Text or Text and images before download; installed models keep those labels. Image support not listed means the available metadata does not declare it. The labels describe accepted inputs, not measured answer quality or support for every Agent operation. Read each release’s limitations.

New detailed releases also declare their architecture, weight format, required engine version, and a memory plan for a stated conversation length. Grid checks these before downloading weights. Memory includes the weights, working space, conversation cache, and headroom. An incompatible release explains whether to update Grid, choose a smaller model, or choose a complete package. Older releases remain usable with their existing checks.

If a publisher restricts downloads, model details link to its terms and access page. Grid does not accept terms for you. Choose an ungated registry release or use an authorized model server; automatic gated downloading is not available. New checkpoints for supported architectures can arrive through registry releases. New architectures or execution features may require a Grid update.

Grid selects a compatible signed variant automatically, preferring an available GPU variant when its memory and platform requirements fit. Installation details and installed models show CPU, Apple GPU (Metal), or NVIDIA GPU (CUDA). The computer summary shows available hardware; each model's label shows its selected runtime. A CPU-only release continues to use CPU even on a Mac with a GPU. Smaller models can help when memory is insufficient.

Apple GPU support uses Metal. Apple Neural Engine execution is not currently available. A new desktop build supplies the acceleration support; the registry must also publish a compatible GPU model release. Existing CPU releases are not changed in place. These labels describe execution support, not a benchmark.

After installation, Installed opens automatically. Try it runs a prompt on this computer and shows the answer and elapsed time, including model loading. Use this model saves it as the Agent and generic workbook AI default. Open Grid Agent continues into chat; Insert in selected cell inserts the matching PREDICT formula and prompt into your selected workbook cell. The same signed model admission and AI function execute both paths. There is no second inference service and no automatic cloud fallback. Existing formulas retain their explicit model choices.

Manage model shows its storage usage and offers removal. Choose another Agent model before removing the selected one. Removing a model can affect workbooks that refer to it. To update, install a newer exact release from Discover, try it, then choose it; earlier versions remain until you remove them. Small models may struggle with complex Agent instructions or structured workbook changes. A successful trial demonstrates execution, not answer quality.

Imported prediction models need a comparison with their original model before use. Compatibility depends on the model, export settings, device, and precision. TensorFlow Lite models preserve fractional floating-point averages; models whose averages were already rounded during loading are refused rather than returning incorrect predictions.

Publishers can explicitly export numeric LightGBM and CatBoost classifiers as label and probability tensors, and the tested MiniLM encoder as normalized embeddings. These recipes preserve declared class order and require explicit input preparation. Model-specific comparisons remain necessary. Weight precision alone does not guarantee identical scores across processors. First-token CPU and Apple GPU checks pass for the tested SmolLM2, Qwen2.5 and Qwen3 models. Apple GPU rounding corrections improve BF16 accuracy. These results do not establish compatibility for every model or GPU. A further F16 activation correction resolves the tested SmolLM2 cached-decoding discrepancy. The tested SmolLM2, Qwen2.5 and Qwen3 BF16 cached scores also meet their original limits after preserving precision through normalization and activation. Equal-score choices now follow the same token order with and without GPU sampling. Low-precision score ties can still select a different word from a full-precision model.

Find extensions

Choose Extensions and search your registry. Open a release, choose the workspace folder, and select Install. Grid verifies the signed release and updates that workspace. Review permissions & activate opens the existing Package Center directly from the completed installation with the selected folder so you can review runtime permissions, activate the extension, and use its functions.

For npm, Python, or another upstream package ecosystem, choose Open Package Center. Its existing package discovery, private upstream-registry credentials, callable selection, and activation controls remain available.

Windows registry installation uses local, private storage. Network drives and redirected state folders are unsupported. The new Windows implementation still needs testing in a packaged Windows desktop build before its behavior is verified.

Choose a registry

Choose Registries. Grid Registry is the default. To use another, enter its name, HTTPS address, and the verification code supplied independently by its administrator. Verify and use registry checks that identity before saving. Have a registry setup link? accepts an administrator-provided grid-registry://setup link or a JSON configuration containing name, origin, and pinnedFingerprint. Import only fills in a draft: review the address and choose Verify and use registry before it becomes active. Previously verified registries are saved for easy switching and verified again when selected. A failed check leaves the current registry selected. Each registry retains its own verification history when you switch away and back.

The selected Grid registry supplies both local-model and signed-extension search and installation. Its search service must provide Grid's /api/search catalog contract. Catalog descriptions are discovery information; installation independently verifies exact signed releases against the saved identity. Private upstream npm/Python registries are configured separately in Package Center because they use a different package protocol.

Follow the setup walkthrough for a complete example.

Ask about images

The upcoming Agent attachment interface accepts PNG and JPEG images using the same provider or local model selected here. Choose Add source → Images, paste, or drop an image into the message box. The same picker offers window/camera capture, video frames, selected image inputs, and earlier conversation images. A vision-capable model is required. See Images, history, and live AI input for limits, workbook use, connector inputs, and historical versus live timing. The first interface supports selected frames from capture previews and local videos where available. Compare a time range gathers two to eight moments from a recording for one question, with their clip positions visible on the attachments. Camera/window previews and selected live image inputs also offer Start observation, with a question, call limit and Stop observation control. Direct PDF, audio, and native video-model input are not included.

With an image attached, Choose an image model opens this setup directly. Your question and attachments stay in place while you choose. Desktop opens local model discovery for images; the browser opens AI providers. Open Grid Agent after selecting a local model returns to Chat in the current workbook.

Agent tasks and teams

Initial AI language release scope

The upcoming AI language release focuses on four workflows: a sequential debate with a judge, shared-document review with human approval, an installed API read followed by agent assessment and an approved service action, and retained memory with checked citations. Author and save a process, bind its participants, then explicitly Start it. Use the Process controls to inspect its conversation, pending human questions, operation results and final output, or cancel the run.

Document, retrieval, memory and service resources require administrator-installed grants for the exact workbook and user. Declaring a resource in source does not grant access. API reads and the specific service-action adapter have different contracts; installing an arbitrary OpenAPI command does not make it an approved process action. Citation checks establish that a cited key belongs to the supplied evidence, not that the answer is factually correct.

External agent messaging, indexed/vector retrieval, dynamic populations and agent-controlled simulation remain follow-on work. The simulation starter is not offered in this release. Process Start offers explicitly installed methods from the selected owner's catalogue; discovery and selection do not execute a method. The full language specification includes planned capabilities beyond this scope.

For native integrations with explicitly installed session and remote operation owners, pending recovery preserves the original conversation, disclosure scope and call budget. Withdrawing a named disclosure changes later turns; FRESH starts a new conversation epoch without erasing accepted history or renewing quota. Read-only inspection makes no new provider calls. This native contract does not install remote authority or expand the initial interface release scope.

A separate Process storage directory is claimed when a Process operation first needs it. Ordinary workbook work leaves that unused directory unclaimed. If another owner holds it, the Process operation refuses to open it. A directory that also contains the host's model data shares the host's startup ownership.

Formatting a Process preserves the recipients of shared fields and computed values. A participant's named saved author, explain or research profile selects its saved provider/model, instructions, step limit and output limit at explicit Start. The language's default remains the AI-setup model binding. Author and research profiles use only supplied-source validation/ evaluation and function lookup; explain has no tools. Profiles cannot inspect the live workbook or add tools. Use author for Grid-source proposals. Author replies use the fixed source-artifact contract and native source checks. Every model call and tool check charges the same Process budget. A conflicting model selection, unsupported external/observe harness or changed original binding refuses instead of running another kind of responder. Process Evaluate uses the same selected harness for each isolated case. Existing agent-task authoring remains available separately.

An uncertain external action must be inspected rather than blindly repeated. Cancellation does not undo an action already accepted by an external service. Restoration availability depends on the selected host and durable resource owners; there is no general exactly-once guarantee. The release scope and remaining acceptance work distinguishes the intended support boundary from completed product evidence.

Configure and run agent tasks

In Chat or the Grid Agent panel, open Tasks. Use AI setup uses the same saved connection as Chat and workbook functions, without entering another model name. Alternatively, choose a provider and exact model for this task. Name the profile and select authoring, explanation, or research. Save profile keeps an instance setting for reuse; shared instances restrict profile changes to administrators. Saved model server uses the connection from AI setup. Administrator-configured servers remain supported when no saved connection exists; external executors retain their separate administrator setup. New tasks follow the latest setup choice; running tasks retain their original model. Resume uses that original connection identity with refreshed credentials.

Enter the task and a maximum number of model calls. Draft, review, and revise with a team runs an author, reviewer and final author in order. The reviewer can use another saved provider/model profile. All tasks share the same call limit; provider calls use your configured account. Tasks keep running when you close the panel. Reopen Tasks to inspect progress, usage and results, or cancel. Unknown token usage stays marked unknown. Cancelling a remote request may leave its outcome uncertain; it does not guarantee that the provider stopped billing.

Choose Images to attach PNG/JPEG files, or open Tasks with images already attached in Chat. Review the thumbnails before starting. A team explicitly shares those images with its reviewer and final author; every selected model must accept images. Task details show image sources. When adding dependent work, Images for the new task lets you explicitly reuse an original source. Recovery records retain the original images until you remove the run; they are private local files, not encrypted image archives. Live capture continues to use Start observation and its separate freshness limits.

Authoring results include proposed source and compiler/evaluation checks. Review the source before choosing Apply proposal to editor. If the editor has changed since submission, start a new task against its current contents. Tasks do not apply changes automatically. The bounded evaluator covers ordinary workbook expressions; connectors, external work and specialized results may remain unevaluated and cannot be presented as clean.

When a supported host offers recovery records, you can retain a run across a restart. Resume is explicit and requires the original model/source and provider bindings. An interrupted request with an uncertain outcome cannot be replayed; inspect it before starting new work. Recovery is currently available on Unix single-host deployments with a configured durable agent store. Other setups keep volatile tasks or report the requested capability as unavailable.

In Instructions and limits, set steps per task, output tokens per call, the shared call limit and the time limit. While a task is active, Send input or add a task lets you queue a follow-up or add dependent work using the selected task's model and instructions. New work shares the original remaining limits. Input is read before the next model call; activity reports messages that arrive too late. Switching workbooks clears the selected run. Removal and application wait until the run's workers stop.

Server editions

Server Lite retains lightweight AI and CPU training, including the built-in small MLP trainer. These capabilities run inside the server process. It does not include standalone AI/training or cloud ingress workers. Server Pro includes these workers and defaults AI/training to process execution. Local LLM, ONNX and XGBoost worker capabilities require the Pro package; turning on a service flag does not install them.

Administrators can select embedded or process with GRID_RUST_AI_BACKEND and GRID_TRAIN_BACKEND. An explicit GRID_RUST_AI_CORE_COMMAND or GRID_TRAIN_CORE_COMMAND also selects process mode unless its backend is specified. If an enabled process worker is missing, startup refuses the configuration instead of trying a placeholder executable. When switching an existing server to Lite, remove pinned Pro worker commands or select embedded mode explicitly. Setting the corresponding *_ENABLED=0 continues to disable the service. These settings do not add GPU support or expand the selected edition's model capabilities.