# How 5ire Handles Offline Mode When Relying on Local Embeddings

> Discover how 5ire masterfully handles offline mode with local embeddings. Learn about its transparent support system for uninterrupted functionality, ensuring full capability without network connectivity.

- Repository: [Ironben/5ire](https://github.com/nanbingxyz/5ire)
- Tags: internals
- Published: 2026-03-07

---

**The 5ire application transparently supports offline mode for embeddings by disabling remote model fetching, enforcing local-only model loading, and validating cached file presence, ensuring full functionality without network connectivity as long as embedding models are stored locally.**

The open-source 5ire application (nanbingxyz/5ire) implements a robust offline-first architecture for its embedding services. By configuring the Transformers.js environment to reject remote requests and strictly validate local model files, the application ensures that text embedding operations continue uninterrupted during network outages.

## Network Status Detection

The application monitors connectivity primarily for user feedback rather than functional gating. A lightweight React hook listens to browser-native events and propagates status changes to UI components.

### The useOnlineStatus Hook

In [`src/hooks/useOnlineStatus.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/hooks/useOnlineStatus.ts), the application attaches event listeners to the browser's `online` and `offline` events. The hook maintains a Boolean flag, `isOnline`, that components consume to render visual indicators.

```typescript
// src/hooks/useOnlineStatus.ts
export default function useOnlineStatus(): boolean {
  const [isOnline, setIsOnline] = useState<boolean>(navigator.onLine);

  useEffect(() => {
    const handleOnline = () => setIsOnline(true);
    const handleOffline = () => setIsOnline(false);

    window.addEventListener('online', handleOnline);
    window.addEventListener('offline', handleOffline);

    return () => {
      window.removeEventListener('online', handleOnline);
      window.removeEventListener('offline', handleOffline);
    };
  }, []);

  return isOnline;
}

```

### UI Feedback Components

The `isOnline` flag drives visual feedback in [`src/renderer/components/layout/WindowsTitleBar.tsx`](https://github.com/nanbingxyz/5ire/blob/main/src/renderer/components/layout/WindowsTitleBar.tsx) and [`src/renderer/components/layout/AppHeader.tsx`](https://github.com/nanbingxyz/5ire/blob/main/src/renderer/components/layout/AppHeader.tsx). These components display network-status icons to alert users of connectivity changes, but critically, the flag **does not** gate embedding logic. The embedder operates independently of this network state, relying instead on local file availability.

```tsx
// Example: UI shows offline status
import useOnlineStatus from 'hooks/useOnlineStatus';
import { WiFiIcon, WiFiOffIcon } from 'some/icon/library';

export default function NetworkIndicator() {
  const online = useOnlineStatus();
  return online ? <WiFiIcon /> : <WiFiOffIcon />;
}

```

## Embedding Service Configuration

The core offline resilience resides in [`src/main/services/embedder.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/main/services/embedder.ts), where the `Embedder` class configures the Transformers.js environment to eliminate network dependencies before loading any models.

### Disabling Remote Model Fetching

During initialization, the embedder explicitly disables remote model access by setting `env.allowRemoteModels = false`. This configuration prevents the Transformers library from attempting HTTP requests to Hugging Face or other model repositories, even if cached files are missing.

```typescript
// src/main/services/embedder.ts
import { env } from '@xenova/transformers';

// Explicitly disable network access for models
env.allowRemoteModels = false;
env.allowLocalModels = true;

```

### Enforcing Local-Only Loading

By pairing the remote disable with `env.allowLocalModels = true`, the application ensures that every embedding request is satisfied solely from the local filesystem. The embedder constructs pipeline instances that resolve paths within the application's `Embedding/Models/` directory, guaranteeing that inference occurs entirely on-device.

## Model File Validation

Before executing embeddings, the service validates that all required model files are present locally. This check prevents runtime errors that would otherwise occur when the system attempts to load non-existent weights.

### File Existence Verification

The embedder references a constant array, `DOCUMENT_EMBEDDING_MODEL_FILES`, which lists all mandatory model artifacts. The service verifies the presence of each file in the local cache folder before transitioning to a `ready` state.

```typescript
// Conceptual validation logic in embedder.ts
const requiredFiles = DOCUMENT_EMBEDDING_MODEL_FILES;
const allFilesPresent = requiredFiles.every(file => 
  fs.existsSync(path.join(MODEL_CACHE_DIR, file))
);

if (!allFilesPresent) {
  this.state = { status: { type: 'unavailable' } };
}

```

### Unavailable State Handling

If any required file is missing, the embedder transitions to an `unavailable` state and returns explicit errors for embedding requests. This failure mode requires user intervention to reinstall the model (an operation needing network connectivity), but it prevents the application from hanging or crashing while attempting impossible network downloads.

## The Offline Embedding Workflow

When a user transitions from online to offline, the embedding pipeline continues functioning through the following deterministic flow:

1. **Network Event Detection**: The browser fires an `offline` event, updating `useOnlineStatus` to `false`. UI components render disconnect icons in [`WindowsTitleBar.tsx`](https://github.com/nanbingxyz/5ire/blob/main/WindowsTitleBar.tsx) and [`AppHeader.tsx`](https://github.com/nanbingxyz/5ire/blob/main/AppHeader.tsx).

2. **Embedding Request Processing**: A request arrives at `Embedder.embed()`. The method checks its internal `ready` state rather than network connectivity.

3. **Local Model Resolution**: Since `env.allowRemoteModels` is permanently set to `false`, the embedder does not attempt internet downloads. It resolves the model path to the local cache directory (`Embedding/Models/...`).

4. **Inference Execution**: If all files in `DOCUMENT_EMBEDDING_MODEL_FILES` exist, the Transformers pipeline loads from disk and returns embedding vectors. If files are missing, the embedder returns an `unavailable` state error.

```typescript
// Example: Embedding while offline (no explicit online check needed)
import { embed } from '@/main/services/embedder';

async function getEmbedding(text: string[]) {
  // The embedder will use the locally cached model.
  const [vector] = await embed(text);
  return vector;
}

```

## Offline Package Management

Beyond embedding models, the application extends offline preferences to Node.js package management. In [`src/mcp.config.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/mcp.config.ts), the downloader configuration includes the `--prefer-offline` npm flag, ensuring that Model Context Protocol (MCP) server installations favor cached copies over network requests when available.

```typescript
// Example: Downloader prefers offline cache for npm packages
const installCommand = [
  'npm', 'install', '--prefer-offline', '@modelcontextprotocol/server-slack',
];

```

This configuration aligns with the embedding service's offline-first philosophy, minimizing network dependencies across the entire application stack.

## Summary

- **Network monitoring is UI-only**: The `useOnlineStatus` hook provides visual feedback but does not gate embedding functionality.
- **Remote fetching is permanently disabled**: `env.allowRemoteModels = false` in [`src/main/services/embedder.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/main/services/embedder.ts) guarantees no network requests for models.
- **Local validation is mandatory**: The embedder checks `DOCUMENT_EMBEDDING_MODEL_FILES` before inference, entering an `unavailable` state if files are missing.
- **Offline works transparently**: As long as model files reside in the local cache, embedding operations proceed normally without internet connectivity.
- **Package management supports offline**: The `--prefer-offline` flag in [`src/mcp.config.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/mcp.config.ts) extends offline resilience to dependency installation.

## Frequently Asked Questions

### Does 5ire block embedding requests when the network is disconnected?

No. The application does not use the network status flag to gate embedding logic. Instead, the `Embedder` class in [`src/main/services/embedder.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/main/services/embedder.ts) checks only for the presence of local model files. If the required files exist in the cache directory, embeddings proceed normally regardless of connectivity state.

### What happens if embedding model files are missing while the user is offline?

The embedder transitions to an `unavailable` state and returns an error for any embedding request. Because `env.allowRemoteModels` is set to `false`, the application cannot download missing files automatically. The user must restore network connectivity to reinstall the model files via the application's downloader.

### How does the UI communicate offline status to users?

Components in [`src/renderer/components/layout/WindowsTitleBar.tsx`](https://github.com/nanbingxyz/5ire/blob/main/src/renderer/components/layout/WindowsTitleBar.tsx) and [`src/renderer/components/layout/AppHeader.tsx`](https://github.com/nanbingxyz/5ire/blob/main/src/renderer/components/layout/AppHeader.tsx) consume the `useOnlineStatus` hook to display network-status icons. When the browser detects an `offline` event, these components render a disconnected indicator, providing immediate visual feedback while the embedding service continues operating in the background.

### Are dependencies installed with offline preferences?

Yes. According to [`src/mcp.config.ts`](https://github.com/nanbingxyz/5ire/blob/main/src/mcp.config.ts), npm install commands include the `--prefer-offline` flag. This instructs the package manager to use cached versions of Model Context Protocol servers when available, reducing installation failures during network outages.