Nextcloud App Guide

Last Updated: 2026-03-09 App Version: 2.0.0

Overview#

The Cloak Anonymizer Nextcloud app brings the full power of cloak.business directly into your Nextcloud instance. With 8 feature tabs, image PII redaction, structured data processing, AI-powered entity creation, and full encryption key management, you can detect and anonymize personal information without leaving Nextcloud.

Key Benefits:

• 8-Tab Interface: Dashboard, Anonymize (3 modes), Image, Structured Data, Presets, Entities, Keys, Settings
• 7 Anonymization Methods: Replace, Redact, Mask, Hash, Encrypt (AES-256-GCM), Asymmetric Encrypt (RSA-4096), Keep
• Image PII Redaction: Detect and redact PII in images (PNG, JPG, BMP, TIFF, WebP)
• Structured Data: Process CSV and JSON files with per-column entity configuration
• AI Entity Creator: Generate custom regex patterns with an AI-powered 5-step wizard
• 220+ Presets: Country-specific, regional, and compliance presets with full CRUD and public library
• 48 Languages: Multi-language PII detection with 320+ entity types
• Server-Side Security: API keys stored on your Nextcloud server, never exposed to the browser

Table of Contents#

1. Requirements
2. Installation
3. Initial Setup
4. Dashboard
5. Anonymize Tab
6. Image Tab
7. Structured Data Tab
8. Presets Tab
9. Entities Tab
10. Keys Tab
11. Settings Tab
12. Companion App: Cloak Files
13. Anonymization Methods
14. Architecture
15. Troubleshooting
16. FAQ

Requirements#

• Nextcloud 28, 29, 30, or 31
• PHP 8.1 or higher
• PHP extensions: json, mbstring, xml, curl
• cloak.business account with API key (get one free)
• Server with outbound HTTPS access to cloak.business

Installation#

Two Apps#

The Nextcloud integration consists of two independent apps:

Both apps share the same API key configuration. If Cloak Files detects a configured Cloak Anonymizer, it reads the API key from there automatically.

Manual Installation#

1. Download tarballs from the releases page:

   • cloak_anonymizer-v2.0.0.tar.gz
   • cloak_files-v1.0.0.tar.gz (optional)

2. Extract to your Nextcloud custom_apps/ directory:

   cd /var/www/nextcloud/custom_apps
   tar xzf cloak_anonymizer-v2.0.0.tar.gz
   tar xzf cloak_files-v1.0.0.tar.gz   # optional
   

3. Set correct permissions:

   chown -R www-data:www-data cloak_anonymizer/ cloak_files/
   

4. Enable the apps:

   sudo -u www-data php /var/www/nextcloud/occ app:enable cloak_anonymizer
   sudo -u www-data php /var/www/nextcloud/occ app:enable cloak_files   # optional
   

Nextcloud App Store#

App Store publication is on the roadmap. For now, use the manual installation method above.

Initial Setup#

1. Open the Cloak Anonymizer app from the Nextcloud top navigation bar
2. The Settings tab appears automatically on first use
3. Enter your API URL: https://cloak.business (default)
4. Enter your API Key: starts with cb_ (get one at cloak.business/pricing)
5. Click Save Settings, then Test Connection — a green checkmark confirms the connection
6. All 8 tabs become available after successful configuration

Your API key is stored server-side only and never sent to the browser.

Dashboard#

The Dashboard tab is the landing page after configuration. It shows:

• Token balance with plan information and monthly usage
• Quick-action buttons to jump to Anonymize, Keys, or Presets tabs
• Usage summary for the current billing period

Anonymize Tab#

The Anonymize tab combines text analysis, anonymization, and decryption into a single unified interface.

Three Modes#

A mode toggle at the top lets you switch between:

Three Input Types#

Below the mode toggle, select the input type:

Config Sidebar#

A collapsible sidebar on the right provides:

• Preset selector — searchable dropdown with 220+ presets
• Language — 48 languages or auto-detection
• Score threshold — slider (0.0–1.0) to filter low-confidence detections
• Entity types — multi-select checkboxes to include/exclude specific types

Entity Review (Anonymize Mode)#

After analysis in Anonymize mode, detected entities appear in an interactive review panel:

• Entities grouped by type, sorted by frequency
• Per-entity operator dropdown: Replace, Redact, Mask, Hash, Encrypt, Encrypt Asymmetric, Keep
• Operator-specific parameters (mask character, hash type, encryption key selection)
• Bulk operator buttons to set all entities at once
• Encryption key selector for Encrypt and Encrypt Asymmetric operators

Results Display#

After processing, results show:

• Highlighted text output (entities color-coded by type)
• Copy Text, Download as TXT, Copy Results JSON buttons
• Token cost display
• Processing time indicator

Decrypt Mode#

For reversing encryption-based anonymization:

1. Paste the anonymized text
2. Select decrypt type: Symmetric or Asymmetric
3. For Symmetric: select the encryption key from your account
4. For Asymmetric: paste the RSA private key PEM
5. Provide the anonymizer results JSON (from the anonymization step)
6. Click Decrypt

Batch Processing#

In Batch mode:

1. Add up to 10 text inputs (add/remove fields dynamically)
2. Click Analyze All — sends a single batch API call
3. Review results per input with a combined summary
4. Apply operators and anonymize individually or all at once

Image Tab#

Detect and redact PII in images directly from Nextcloud.

Supported Formats#

PNG, JPG, BMP, TIFF, WebP — maximum 10 MB per image.

Image Analysis#

1. Upload an image via drag-and-drop, file input, or Nextcloud file picker
2. Select language and entity types
3. Click Analyze Image
4. Detected entities appear as colored bounding boxes overlaid on the image
5. Each box is labeled with entity type and confidence score

Image Redaction#

1. After analysis, click Redact Image
2. Choose a fill color: black (default), white, or custom hex
3. The redacted image downloads with all detected PII areas filled
4. Optionally deselect specific entities to exclude them from redaction

Structured Data Tab#

Process CSV and JSON files with per-column anonymization configuration.

CSV Processing#

1. Upload a CSV file
2. Columns are auto-detected from the header row
3. Configure each column: select entity types to detect and the operator to apply
4. Preview the first 5 rows before processing
5. Click Process — the anonymized CSV downloads

JSON Processing#

1. Paste or upload a JSON array of objects
2. Keys are auto-detected from the first object
3. Configure per-key entity types and operators
4. Click Process — the anonymized JSON is displayed and downloadable

Column Configuration#

For each column/key, you can set:

• Entity types to detect (multi-select)
• Operator to apply (Replace, Redact, Mask, Hash, Encrypt, etc.)
• Skip toggle to exclude the column from processing

Presets Tab#

Full management of anonymization presets with three sub-tabs.

My Presets#

Your custom presets. Create, edit, duplicate, or delete presets.

Each preset defines:

• Name and description
• Language
• Score threshold
• Entity types to detect
• Per-entity operator configuration

Default Presets#

220+ built-in presets (read-only):

• Country-specific (85+): Germany, USA, UK, France, Japan, Brazil, etc.
• Regional (15): European Union, ASEAN, Americas, etc.
• Compliance: GDPR, HIPAA, PCI-DSS, SOX, ISO 27001
• Industry: Healthcare, Financial, Government, Legal

Toggle favorites to quickly access the presets you use most.

Public Library#

Browse and import community-shared presets:

• Search by name or category
• Preview preset configuration before importing
• Click Import to add a public preset to your My Presets collection

Entities Tab#

Create and manage custom entity types with two sub-tabs.

My Entities#

Your custom entity definitions. Each entity has:

• Name (uppercase, e.g., EMPLOYEE_ID)
• Description
• Category (personal, financial, medical, custom, etc.)
• Patterns — one or more regex patterns with name and confidence score

Create Manually#

1. Click Create Manually
2. Enter name, description, category
3. Add regex patterns (name + regex + score slider)
4. Use the live regex tester to validate patterns against sample text
5. Click Save Entity

Create with AI (AI Entity Wizard)#

A 5-step wizard powered by AI:

1. Basics — name, description, category
2. Examples — add positive examples (should match) and negative examples (should not match)
3. Generate — AI generates regex pattern suggestions ranked by quality, precision, and recall
4. Refine — add more test cases, click Refine to improve patterns
5. Review — summary of the final entity with all patterns, click Save

The AI wizard requires an AI provider configured in Settings (OpenAI, Anthropic, or Abacus.ai).

Public Entity Library#

Browse and import community-shared entity definitions. Click Import to add a public entity to your collection.

Keys Tab#

Full CRUD management for encryption keys with two sub-tabs.

Symmetric Keys (AES-256-GCM)#

• View all symmetric keys (name, length, creation date)
• Create Key: enter a name + raw key value, or generate a random 16/24/32-byte key
• Reveal: show the decrypted key value (click to toggle)
• Rename: update the key name
• Delete: permanently remove (with confirmation — encrypted data becomes unrecoverable)
• Copy: copy key value to clipboard

Asymmetric Keys (RSA-4096)#

• View all RSA key pairs (name, fingerprint, active/inactive status, creation date)
• Generate RSA-4096: generates a new key pair in the browser using WebCrypto, uploads PEM to the server
• View Keys: expand to see both public and private key PEM data
• Copy PEM: separate copy buttons for public key and private key
• Toggle Active: activate or deactivate a key pair
• Delete: permanently remove (with confirmation — encrypted data becomes unrecoverable)

Settings Tab#

Four configuration sections:

API Connection#

• API URL (default: https://cloak.business)
• API Key (masked display, cb_...)
• Test Connection button with health check, auth validation, and token balance

AI Provider#

Configure an AI provider for the Entity AI Wizard:

• Provider dropdown: OpenAI, Anthropic, Abacus.ai
• API key input (masked)
• Model selector
• Test Connection button

Defaults#

Set default values for new anonymization operations:

• Default language
• Default operator
• Default score threshold

Token Balance#

• Current token balance and plan information
• Monthly usage breakdown

Companion App: Cloak Files#

The optional Cloak Files app adds file-level integration:

Sidebar Tab#

1. Open any text file in Nextcloud Files
2. Click the sidebar details panel
3. Click the Cloak tab
4. File content loads automatically
5. Analyze, preview, and anonymize from the sidebar

Right-Click File Action#

1. Right-click any supported text file in Nextcloud Files
2. Select Anonymize with Cloak from the context menu
3. Opens the Cloak Anonymizer app with the file loaded in the Anonymize tab

Shared Configuration#

Cloak Files reads the API key from Cloak Anonymizer if both apps are installed. If only Cloak Files is installed, configure the API key in its own settings.

Anonymization Methods#

Architecture#

Browser                    Nextcloud Server              cloak.business API
┌──────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
│  Vue 3 App   │───>│  PHP OCS Controller  │───>│  /api/presidio/*     │
│  26 comps    │    │  ApiController (42)   │    │  /api/encryption-keys│
│  51 API fns  │    │  SettingsController   │    │  /api/asymmetric-keys│
│  (ES Module) │<───│  CloakApiService     │<───│  /api/presets        │
└──────────────┘    │  (Guzzle HTTP)       │    │  /api/entities       │
                    │  51 OCS routes        │    │  /api/ai/*           │
                     API key stored here     │    │  /api/structured/*   │
                     (IConfig, per-user)     │    └──────────────────────┘
                    └──────────────────────┘

The API key never leaves your Nextcloud server. All browser requests go through the Nextcloud OCS API, which adds the API key server-side before forwarding to cloak.business.

Stats: 26 Vue components, 51 OCS API routes, 51 frontend API functions, 105 PHPUnit tests, 160 E2E tests.

Troubleshooting#

"Connection failed" when testing settings

• Verify your Nextcloud server can reach https://cloak.business (outbound HTTPS on port 443)
• Check your API key starts with cb_ and is valid

No entities detected

• Try a lower confidence score threshold (e.g., 0.3)
• Ensure you selected the correct language for your text
• Try a preset that includes the entity types you expect

"Anonymize with Cloak" not showing in right-click menu

• Ensure Cloak Files is installed and enabled: php occ app:list | grep cloak
• The file action only appears for supported text-based MIME types
• Try reloading the Files page

Permission errors when saving files

• Ensure the www-data user owns the app files: chown -R www-data:www-data custom_apps/cloak_anonymizer/
• Check Nextcloud logs at /var/log/nextcloud/nextcloud.log

Image analysis returns no results

• Ensure the image contains text-based PII (names, emails, etc.)
• Try a different language setting
• Images must be under 10 MB

AI Entity Wizard not available

• Configure an AI provider in Settings > AI Provider
• Test the connection to verify the AI API key is valid

FAQ#

Is the Nextcloud App free? The app itself is free and open-source (AGPL). It uses the cloak.business API, which has a free plan with 200 tokens per month. Paid plans start at €3/month.

Where is my data processed? Text is sent to cloak.business API servers in Falkenstein, Germany (ISO 27001-certified). Data is processed in memory and immediately discarded.

Can I self-host the detection engine? The app currently requires the cloak.business API. Self-hosted deployment is not available yet.

Does it work with Nextcloud Hub? Yes. The app is compatible with Nextcloud 28–31, including all Nextcloud Hub editions.

Can I use the app alongside the web app and desktop app? Yes. All cloak.business clients (Nextcloud, web, desktop, Chrome extension, Office add-in) share the same account, token balance, encryption keys, and presets.