ISA Warden Documentation.

ISA Warden is a local-first AI desktop platform. Its primary user-facing app is chat-ui-3, a SvelteKit and Tauri desktop application, with Rust-based local backend logic in chat-ui-3/src-tauri. It combines chat, local or remote AI models, workspaces, document handling, agents, tools, dashboard administration, and extensions.

Local-first means the app is designed to keep core AI interaction and application behavior available on the user’s computer where possible. Local models, local app data, and desktop integration are central parts of the product. Some features, such as dashboard workspaces, cloud accounts, artifact storage, invitations, private servers, or shared resources, may require network access or a dashboard service.

No. Chat is the primary interaction surface, but the app also includes workspaces, groups, roles, model management, document retrieval, agents, tools, extension hosting, file and artifact management, feedback review, and private server integration.

The main interface is chat-ui-3, built with SvelteKit, TypeScript, Vite, and Tauri. The desktop shell and local backend are implemented under chat-ui-3/src-tauri.

ISA Warden has a dashboard stack in isa_dashboard. It provides Rust gRPC server/client infrastructure, protocol definitions, dashboard routes, workspace management, resource management, permissions, and related service-side functionality.

Yes, the UI contains an explicit dashboard-inaccessible state saying the dashboard may be unreachable because of no internet connection or the dashboard being offline, and that the rest of the application can still be used. Dashboard-dependent operations will not work until connectivity or service availability is restored.

Not always. The onboarding flow supports signing in, creating an account, continuing as the current user, or continuing offline. Cloud/dashboard features, shared workspaces, invitations, uploads, and administrator workflows may require an authenticated account.

A local account is used on the current device and is suitable for local or offline workflows. A cloud/dashboard account enables shared workspaces, invitations, dashboard resources, and authenticated dashboard operations.

Yes, the onboarding text includes a “Continue Offline” path. Offline use is appropriate for local workflows. However, online features such as dashboard access, workspace invitations, artifact uploads, remote model servers, updates, web search, and cloud resources may require network access.

The onboarding flow guides the user through three main areas:

1. Account setup: sign in, continue offline, or use an existing account.
2. Workspace setup: choose, join, or create a workspace.
3. Model setup: select an AI model suitable for the device and workflow.

The onboarding UI estimates approximately 1–5 minutes.

Yes. The onboarding copy explicitly says settings can be changed later, and the app includes settings, workspace selection, model management, and dashboard management screens.

The onboarding flow includes errors for failed workspace loading, failed invitation loading, failed workspace creation, and failed invitation acceptance. In practice, this usually means the app could not reach the dashboard, the user session is invalid, the workspace name is invalid or already used, or permissions are insufficient.

A workspace is the main organizational container in ISA Warden. It holds members, groups, roles, models, agents, tools, servers, files, artifacts, extensions, and feedback resources.

A group is a workspace subdivision used to control which members can access which resources. Groups can be linked to models, tools, agents, files, and members.

A role is a collection of permissions assigned to workspace members. Roles control administrative abilities such as managing the workspace, roles, invites, members, groups, models, agents, tools, servers, feedback, and resource links.

The extension specification and dashboard references include examples such as manage workspace, manage roles, invite users, manage users, manage groups, manage group members, manage models, manage agents, manage tools, manage servers, link resources, view feedback, and delete feedback.

Users with the relevant invitation permission can invite members. The dashboard UI also supports group-level invitation workflows where users may invite or add members to a group if they have sufficient rights.

Pending invitations appear during onboarding and in workspace views. Until accepted, workspace content stays hidden. Accepting the invitation unlocks workspace content according to the groups and permissions assigned to the user.

Yes. The app includes a decline invitation flow with confirmation.

Yes. The dashboard includes a leave workspace action. The confirmation text states that leaving is irreversible and removes access to all workspace data for that user.

Yes, if they have the required rights. Removing a member from a workspace also removes them from all groups inside that workspace, and they can only be re-added by invitation.

Yes. The dashboard includes rename actions for workspaces and groups, with validation that names cannot be empty.

A thread is a conversation in ISA Warden. Threads contain messages, selected model context, optional documents, conversation settings, and in some cases agent synchronization state.

The UI includes a thread search component and a threads sidebar, so thread browsing and searching are part of the app’s chat workflow.

Conversation settings include model-related and behavior-related controls such as the selected model, token window, and agent synchronization. The exact settings available depend on the selected workspace, model, and agent state.

The thread sidebar can show that an agent is out of sync with thread settings. Syncing with the agent replaces the conversation’s system prompt with the agent instructions.

Yes. The thread message UI includes a mention picker for agents and documents.

The chat UI lists support for images and documents. Supported image types include PNG, JPG, GIF, WebP, and BMP. Supported document types include PDF, DOCX, XLSX, PPTX, CSV, and HTML.

The app shows an unsupported file error and lists supported types.

Yes, but only when the current model supports vision/image input. If the current model does not support images, the app asks the user to select a vision-capable model, remove images, or continue in a copy of the conversation without images.

Tool calling may be unavailable because the selected model is not trained for tool use or because the token window is too small. The UI indicates that efficient tool calling requires a minimum 32k token window.

ISA Warden supports local models, remote/private server models, and cloud-connected models as represented in the dashboard model source and location fields.

A local model is stored and run on the user’s computer. The UI supports GGUF model downloads, local model loading, unloading, and status tracking.

GGUF is a model file format commonly used by local LLM runtimes such as llama.cpp. ISA Warden’s onboarding and dashboard flows include GGUF model selection, downloads, memory checks, and optional vision files.

The onboarding model selection flow ranks GGUF models based on device suitability and presents small, medium, and large tiers. Small models are fastest but lower quality, medium models balance speed and capability, and large models provide best capability but slower responses.

Model fit indicators describe how suitable a model is for the current device. Examples include perfect fit, good fit, marginal fit, and not supported.

Yes. The dashboard model flow includes memory requirement checks. It can show safe, caution, high-risk, or unknown states. If a model requires more memory than available, the operation may be blocked.

Swapping happens when the system uses disk storage as overflow memory. The app warns when a model may cause memory swapping because it can significantly reduce performance.

Yes. The dashboard includes a Hugging Face Hub model source and GGUF model browsing/selection flow.

Yes. The dashboard supports adding models using a download link, including optional vision file links for multimodal models that require a separate file.

Some vision-capable local models require a paired GGUF vision projection file, often represented in the UI as a vision file or mmproj file. This file enables image input for compatible local models.

The onboarding flow includes a warning that image support may not work and asks the user whether to download it anyway as a text model or cancel and choose another model.

Yes. The dashboard supports private servers with server name, address, API key, model fetching, and adding server-provided models to a workspace.

Model statuses include inactive/unloaded, loading, active/loaded, downloading, failed, and not downloaded.

The app can show that the llama.cpp backend exited before the model was ready or that the backend could not launch the selected model. The user can switch to another available model if one exists.

Yes. The app supports document upload/attachment, document processing, document search, and retrieval against thread-attached files.

Document processing extracts text and prepares it for retrieval. The UI distinguishes fast extraction, high-quality extraction, ready state, and failed state.

It means a faster extraction pass is already available for use while a higher-quality extraction pass is still processing.

Yes. Built-in tools include document search, document listing, and chunk-level document reading for documents attached to the current conversation.

No. The extension specification clarifies that being present in vector storage does not automatically make a document part of every chat. Retrieval depends on which files are attached to or allowed for the specific thread/request.

Yes. Retrieval settings support tagged files and a maximum chunk count, allowing the request to constrain which attached documents should be used.

An agent is a configured AI assistant inside a workspace. It has a name, description, instructions, creativity level, assigned tools, and group availability.

Agent instructions define the behavior and purpose of the agent. Syncing an agent to a thread can replace the conversation’s system prompt with those instructions.

The dashboard supports creativity levels such as strict, neutral, and loose. These control how constrained or creative the agent should be.

Yes. Agents can be assigned tools available in the workspace. Whether tool use works in a conversation also depends on the selected model’s tool-calling capability and token window.

Yes. Agents can be managed across group memberships, making them available only to specific groups where appropriate.

The dashboard indicates that agent creation requires administrator privileges in the current workspace.

Tools extend what AI models and extensions can do. They can provide calculation, web access, document retrieval, webpage extraction, and other capabilities.

Built-in tools defined in isa-objects/src/builtin_tools.rs include:

1. Calculator
2. Web Search
3. Extract Webpage Text
4. Browse and Extract
5. Search Documents
6. Documents in Conversation
7. Read Document

The calculator supports arithmetic and scientific operations such as addition, subtraction, multiplication, division, powers, modulo, square roots, trigonometric functions, logarithms, exponentials, rounding, min/max, degrees/radians conversion, factorial, and related operations.

Web Search searches the web using DuckDuckGo and returns results.

It extracts text content from a webpage and converts it to a markdown-like format.

It uses browser-based page loading to extract content, which is useful for pages requiring dynamic rendering.

Document tools list documents in the current conversation, search document chunks, and read specific chunks or all chunks from a document.

The dashboard supports adding tools with types such as web search, code execution, file access, API integration, custom, and scripted. Actual availability depends on workspace configuration and implementation.

The UI supports a scripted tool type with script code. The dashboard labels it as Rune script code. Its exact behavior depends on the configured tool runtime and workspace permissions.

The dashboard is the administrative area for managing workspaces, access, members, models, tools, agents, servers, files, artifacts, extensions, feedback, roles, and permissions.

Administrators can manage workspace structure, groups, members, invites, roles, permissions, models, agents, tools, servers, files, artifacts, extensions, and feedback, depending on their assigned permissions.

Dashboard resources include workspaces, members, models, agents, tools, servers, pending invites, permission definitions, and current user permissions.

It means the current user does not have permission to perform the requested action. Some actions require administrator privileges or a specific role permission.

Feedback entries are user feedback records, including positive/negative ratings, optional user comments, conversation context, timestamps, and raw data. Only administrators or users with feedback permissions can view or manage them.

Yes. The dashboard includes an export JSON action for feedback entries.

Yes, if the user has the required permission. Deleting feedback is a destructive action.

Workspace files are files stored inside a workspace folder structure. They can be uploaded, replaced, downloaded, deleted, filtered, sorted, linked to groups, and assigned visibility/write policies.

The dashboard shows metadata such as name, kind, size, content type, owner, extension, updated time, visibility, write policy, parent folder, and linked groups.

Yes. The dashboard includes a replace workflow that keeps the file ID, name, permissions, and links while replacing only the contents.

Artifacts are uploaded files stored through artifact storage, often backed by S3-compatible endpoints. Uploaded model artifacts and workspace-linked files can appear as artifacts.

An artifact storage endpoint defines where new artifact uploads go. It includes details such as endpoint URL, region, bucket, public base URL, key prefix, path-style setting, and credentials.

No. The dashboard states that new uploads use the active endpoint, while existing artifacts keep the endpoint they were uploaded through.

Yes. The app can create signed download links for artifacts. Signed links are temporary and should be treated as sensitive.

Yes, unless they are still in use. If an artifact is used by a workspace file, it must be deleted or replaced there first.

A server is a configured private API endpoint that can provide models to a workspace. It includes a name, server address, optional API key, and discoverable available models.

Yes. The server modal includes actions for loading available models from the server and adding a selected model to the workspace.

The dashboard shows a models fetch error. Common causes include wrong server address, invalid API key, server downtime, incompatible API shape, or network failure.

Yes. Model source types include local file, HTTP download, dashboard artifact, and API connection.

Extensions are packaged add-ons that run inside ISA Warden and integrate with the host through a browser bridge. They can provide custom UI, use host commands, call native code when allowed, access workspace files when permitted, and interact with chat or document workflows.

The preferred extension architecture is Svelte for UI, Rust native binaries when native logic is required, and host integration through the ISA Warden extension bridge.

An extension requires an extension manifest and an entry file. Optional assets include native binaries, packaged frontend assets, local build scripts, and extension documentation.

Dashboard-distributed extensions use a package root with an extension metadata file and a compressed payload archive. The package suffix is .ISAWardenExtension.

Yes, but only when declared correctly. If native functionality is used, the extension must define native binaries and request the native code permission.

Extensions declare permissions for host capabilities such as app information, thread access, native code, filesystem read/write/delete, and other host commands. Extensions should request minimal permissions.

No. Extensions operate inside the authority of the current user. Access requires user rights, resource visibility, declared extension capability, and host policy allowance.

Yes, when permitted. Workspace filesystem commands allow listing files, uploading files, storing JSON, downloading via signed links, and deleting files, depending on permissions.

Yes, through the host email command when supported and permitted. The authenticated user’s email is derived server-side; extensions must not spoof the current user’s email.

Yes. The extension bridge exposes built-in tools directly and through an MCP-shaped discovery/invocation layer.

Yes. Extensions can create extension-scoped threads, optionally hidden from the main thread list, with required extension context fields.

Usually no. The extension specification recommends host storage, thread APIs, workspace file APIs, and document snapshot APIs before introducing a custom extension-owned database.

ISA Warden is designed around local-first operation and secure/private messaging, but privacy depends on the selected workflow. Local models and local accounts can keep more work on-device. Cloud accounts, remote servers, artifact uploads, web search, dashboard services, and extensions may involve networked systems.

Local account state, local models, local conversations, logs, model files, and local app data may reside on the device depending on configuration. The settings UI includes actions for opening the local models folder and deleting local application data.

Yes. The settings danger zone includes an action to delete all locally stored application data on the device. The app reloads afterward.

Yes. The settings danger zone includes account deletion. Whether this deletes only local state or also dashboard/cloud state depends on the account type and server-side behavior.

The dashboard supports server API keys and artifact storage credentials. These should be treated as sensitive secrets. Access should be restricted through roles and permissions.

Dashboard permissions are enforced server-side through route permission checks, and the UI also hides or disables actions when the user lacks permission.

No. Signed links grant temporary access to a file or artifact. They should only be shared with intended recipients and treated as sensitive until expiration.

Settings include profile overview, account type, profile picture, appearance, theme, text size, security/password actions, AI model management, logs, installation diagnostics, debug controls, account deletion, and local data deletion.

Yes. The settings include light, dark, and system theme options.

Yes. Text size options include default, comfortable, and large.

Yes. The settings include a profile picture change action.

Yes, if the account supports it. The app validates current password, new password, confirmation, and minimum length.

The project includes English and Dutch language packs under chat-ui-3/src/langs/en and chat-ui-3/src/langs/nl.

Yes. The app includes update checking, update download, installation, update notifications, and post-update changelog display.

Notifications include application updates, model downloads, OCR downloads, generic downloads, progress updates, pauses, failures, cancellations, and completion states.

The notification UI includes pause and resume actions, and progress states for downloads.

The app can show a changelog modal describing what is new in the installed version. If no changelog is provided, it shows an empty changelog message.

The app shows an update error. Typical causes include network failure, unavailable update service, invalid update metadata, or local installation issues.

The dashboard may be offline, unreachable, or blocked by lack of internet connection. The app indicates that the rest of the application can still be used.

A model is required to start a chat. If no model is selected or available in the workspace, select or add a model first.

Messages can wait while a model is loading, unloaded, downloading, preparing after download, or while the assistant is still responding.

The selected model may not be downloaded or available at its expected location. The app can ask whether to continue downloading the model.

The selected local model may not support images, or the conversation may contain images while the selected model is text-only. Switch to a vision-capable model, remove image messages, or continue in a copy without images.

Tool calling can fail if the selected model does not support tool use, the token window is too small, the tool call exceeds maximum recursion depth, or the tool itself fails.

The device may not have enough disk space, the model may require too much memory, or the download URL may be missing or invalid.

Uploads usually require sign-in and dashboard access. Artifact uploads also require an active storage endpoint and valid storage configuration.

An artifact cannot be deleted while still used by a workspace file. Delete or replace the dependent workspace file first.

Your role may lack the required permission. Ask a workspace administrator to grant the relevant role permission or perform the action.

The settings include an application logs screen with actions to copy or clear logs. Logs are intended for troubleshooting and support.

Admins should create or select a workspace, invite members, define roles, create groups, add models, configure agents/tools/servers as needed, and verify that members only see the resources they should access.

Use roles with the minimum required permissions. Avoid giving broad administrator rights unless the user needs full workspace administration.

Admins can add local/downloaded models, dashboard artifact models, API-connected models, Hugging Face models, and private server models. They should verify memory fit, group availability, safety level, and source details.

Admins should add only tools needed by the workspace, assign them to appropriate groups, and consider whether selected models can actually use tools.

Admins should store correct server address and API key values, test model fetching, add only required server models to the workspace, and remove or reconfigure models before deleting a server.

Admins should review extension author, version, permissions, native code usage, persistence behavior, dashboard resource access, and data retention before adding an extension.

The core components are chat-ui-3, chat-ui-3/src-tauri, isa_dashboard, and isa-objects.

The frontend is under chat-ui-3/src, with route and component files under chat-ui-3/src/routes.

General commands are in chat-ui-3/src-tauri/src/commands/mod.rs. Dashboard commands are in chat-ui-3/src-tauri/src/dashboard_commands/mod.rs. Commands must also be registered in chat-ui-3/src-tauri/src/lib.rs.

Dashboard protocol definitions are in isa_dashboard/isa_dashboard_proto/proto/isa_dashboard.proto, and routes are registered through isa_dashboard/isa_dashboard_server_lib/src/routes/mod.rs.

Shared built-in tool definitions are in isa-objects/src/builtin_tools.rs. Runtime tool implementations are under chat-ui-3/src-tauri/src/model_engine/rig_tools.

For Svelte or JavaScript UI changes in chat-ui-3, run the project’s build validation command from that directory.

For Rust changes, run compile checks and tests. If the changes are in the Tauri app, run them from chat-ui-3/src-tauri.

All user-visible UI strings must use static translation keys, and English and Dutch language packs must stay synchronized under chat-ui-3/src/langs/en and chat-ui-3/src/langs/nl.