Wigolo Local-Only Data Storage Security Model: Complete Technical Guide

Wigolo's security model ensures all persistent data remains on the user's machine under ~/.wigolo/, utilizing OS keychain integration or AES-256-GCM encryption for secrets, with zero external transmission unless explicitly configured.

Wigolo, developed by KnockOutEZ, implements a privacy-first architecture designed to keep sensitive information completely offline. The security model for Wigolo's local-only data storage guarantees that database files, credentials, and telemetry remain under the user's control within the ~/.wigolo/ directory. According to the source code documented in docs/privacy-security.md, the application enforces strict local persistence with cryptographic fallbacks and minimal network exposure.

How the ~/.wigolo/ Directory Structure Enforces Security

The data directory defaults to ~/.wigolo but can be relocated via the WIGOLO_DATA_DIR environment variable. Every component within this directory follows the principle of local-only persistence, ensuring that deleting ~/.wigolo removes all application state without remote residue.

Database Files and Caches

Persistent storage uses SQLite databases that never transmit data to external servers:

• wigolo.db – Stores the knowledge cache, including crawled pages and search indexes
• jobs.db – Maintains metadata for watch jobs and scheduled tasks
• Model caches – Downloaded only from public distribution sites during init or warmup operations, with no license-check phone-home mechanism

As specified in docs/privacy-security.md (lines 11-13), these files remain strictly on-device and are excluded from any cloud synchronization unless the user explicitly configures external backup tools.

Configuration and Non-Secret Settings

The config.json file contains only non-sensitive user preferences, such as search backend selection and UI themes. By design, this file excludes secrets, which are instead managed through the OS keychain or encrypted storage. This separation prevents accidental credential exposure in plaintext configuration files.

Plugin Isolation and Shell History

Third-party extensions and interaction logs are sandboxed within specific subdirectories:

• plugins/ – Contains installed plugin code, isolated from core application logic
• skills/receipts.json – Records plugin installation metadata for dependency tracking
• shell-history/ – Stores interactive command history readable only by the local user

These isolation boundaries prevent cross-contamination between plugins and ensure that shell interactions remain private to the local system.

Cryptographic Protections for Sensitive Data

Wigolo implements a tiered approach to secret management, prioritizing OS-native security before falling back to application-level encryption.

OS Keychain Integration

When available, Wigolo stores API keys and credentials directly in the operating system's keychain (Keychain Access on macOS, Credential Manager on Windows, or libsecret on Linux). This delegates encryption and access control to battle-tested OS security mechanisms, ensuring secrets remain inaccessible to other users or applications running under the same account.

AES-256-GCM Fallback Encryption

If no OS keychain is detected, Wigolo automatically falls back to storing secrets in the keys/ subdirectory using AES-256-GCM encryption. This directory contains encrypted credential files that protect against offline attacks while maintaining zero external dependencies. The encryption keys are derived from machine-specific entropy, ensuring that copied data directories cannot be decrypted on other hardware.

Network Isolation and Runtime Hardening

Beyond storage encryption, Wigolo's security model restricts network behavior to prevent data exfiltration and server-side request forgery.

SSRF Protection and Egress Controls

By default, URL-taking APIs refuse connections to private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and loopback addresses (127.0.0.1/8) unless the user explicitly sets WIGOLO_FETCH_ALLOW_PRIVATE=true. This SSRF protection prevents malicious content from probing internal network services.

Outbound connections are strictly limited to:

• Target search engines and websites specified in queries
• Configured LLM provider endpoints
• Optional telemetry endpoints defined by WIGOLO_TELEMETRY_ENDPOINT

No vendor-owned backend receives data unless the user opts in, as documented in docs/privacy-security.md (line 27).

Daemon Mode Security

When running in serve mode, Wigolo implements fail-closed defaults:

• daemon-admin.token – Generated with owner-only permissions (0600) on each daemon start, required for authenticated admin routes
• Host/Origin validation – Blocks requests with hostile Host or Origin headers to prevent DNS rebinding attacks
• Bearer token authentication – Privileged API routes require valid bearer tokens, ensuring that even locally-bound services resist unauthorized access

Managing Local Data Programmatically

The Wigolo SDK provides type-safe methods to interact with the local data store while respecting its security boundaries.

Locating the Data Directory

import { getConfig } from 'wigolo';

// Resolve the active data directory (respects WIGOLO_DATA_DIR overrides)
const config = getConfig();
console.log('Wigolo data directory:', config.dataDir);

Reading Configuration Safely

import { readFileSync } from 'fs';
import { join } from 'path';
import { getConfig } from 'wigolo';

const cfgPath = join(getConfig().dataDir, 'config.json');
const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
console.log('Configured search backend:', cfg.searchBackend);

Storing Encrypted Credentials

import { storeKey } from 'wigolo/keystore';

// Automatically uses OS keychain or falls back to AES-256-GCM in ~/.wigolo/keys/
await storeKey('openai', process.env.OPENAI_API_KEY!, { 
  dataDir: getConfig().dataDir 
});

Complete Data Erasure

import { execSync } from 'child_process';
import { getConfig } from 'wigolo';

// Removes all local state, databases, and encrypted keys
execSync(`rm -rf ${getConfig().dataDir}`, { stdio: 'inherit' });

Summary

Wigolo's local-only storage architecture achieves comprehensive security through:

• Local-only persistence – All state lives in ~/.wigolo/; no remote data retention by default
• Secret isolation – Credentials protected by OS keychain or AES-256-GCM encryption, never stored in plaintext config files
• Minimal network exposure – Outbound traffic restricted to user-intended services; telemetry requires explicit opt-in via WIGOLO_TELEMETRY=1 and endpoint configuration
• Built-in hardening – SSRF guards, DNS rebinding protection, and token-based daemon authentication assuming untrusted network environments

Frequently Asked Questions

How does Wigolo handle API keys if my system lacks a keychain?

When no OS keychain is available, Wigolo automatically encrypts API keys using AES-256-GCM and stores them in the ~/.wigolo/keys/ directory. The encryption uses machine-specific entropy, ensuring the files cannot be decrypted if copied to another device.

Can Wigolo's local database files be moved to a different machine?

Yes. Since all data resides under ~/.wigolo/, you can relocate the entire directory to another system. However, if you used the fallback encryption for credentials (rather than the OS keychain), those encrypted keys will not decrypt on the new hardware due to machine-specific encryption keys.

Is any data transmitted when I use Wigolo's search features?

No local data is transmitted during standard operation. Wigolo contacts only the target search engines or websites specified in your query, plus your configured LLM provider when using AI features. According to docs/privacy-security.md, the application performs no license checks or telemetry transmission unless you explicitly enable WIGOLO_TELEMETRY and define a WIGOLO_TELEMETRY_ENDPOINT.

What happens to the daemon-admin.token when the server restarts?

The daemon-admin.token file is regenerated with fresh cryptographically secure random bytes on every daemon startup. It is created with owner-only permissions (mode 0600) and required for accessing administrative HTTP routes, ensuring that previous tokens cannot be replayed after a restart.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}