Browse documentation

๐Ÿงญ Start Here

Blackcap Overview โœจ Blackcap Feature Catalog ๐Ÿค– AI Features ๐Ÿงฑ Technology, Administration, and Reliability Installation First Run

๐Ÿ“˜ User Guides

Administration and Operations Platform Configuration Organization Configuration Email and Consent Management

๐Ÿš€ Deploy Blackcap

Platform Stacks and Raspberry Pi Hardware Raspberry Pi Deployment Raspberry Pi Client Services GCP Deployment Packaged Blackcap deployment Application Updates After Your First Blackcap Login: Self-Hosted Setup Guide Blackcap Release Notes Environment Variables and Secrets Reverse Proxy and TLS Background Jobs and Schedules

๐Ÿ› ๏ธ Administer Blackcap

Organizations Users, Permissions, and Authentication Configuration Workspace Backups and Restore Database Administration Regression Testing Performance and Job Status Audit, Access Activity, and Logging GeoIP and Access Location Data Retention and Purge Support Chat Administration Support Requests API Tester and Postman Instance Reporting Third-Party Packages and Attribution AI Provider Usage and Billing Portals Microwave Pie licensing for Blackcap Microwave Pie licensing for Blackcap

๐Ÿฝ๏ธ Use Recipes

Recipes and the Recipe Library Recipe Import and Discovery Recipe Editing and Cache Artifacts Recipe Sharing Social Recipe Import AI Recipe Image Generation ๐Ÿช„ Adapt Recipe and ๐ŸŽฒ Variations

๐Ÿ“… Plan Meals

Meal Planner

๐Ÿ›’ Use Shopping Lists

Shopping Lists and Shop a List External and Household Shopping ๐Ÿ”— Chrome Extension Shop With

๐Ÿงบ Manage Kitchen Inventory

๐Ÿงบ Kitchen Inventory

๐Ÿ–ฅ๏ธ Use Displays

Displays and Connections Assigning and Scheduling Display Content Remote Pi Client E-Ink Rendering Menu Refresh and Rendering Noun Project Footer Images

๐Ÿง‘โ€๐Ÿณ Cook with Letโ€™s Cook

๐Ÿง‘โ€๐Ÿณ Letโ€™s Cook ๐Ÿง‘โ€๐Ÿณ Letโ€™s Cook Controls and Timers

๐Ÿค– Use and Administer AI

๐Ÿค– AI in Blackcap ๐Ÿค– AI Providers and Connections ๐Ÿค– AI Seeds and Usage Support Chat

๐Ÿ”— Use the Chrome Extension

๐Ÿ”— Blackcap Chrome Extension ๐Ÿ”— Chrome Extension Recipe Capture ๐Ÿ”— Chrome Extension Shop With ๐Ÿ”— Chrome Extension Release and Privacy

๐ŸŽฎ Play Games

Games and trivia Bramble Harvest โ€” Player Guide Flavor Lab โ€” Player Guide

๐Ÿ”Œ Integrations

Email Integration Cloud Storage Integrations Voice Assistants Shop With Integrations Authentication Providers

โš™๏ธ Develop Blackcap

Application Architecture Database Service and Data Access SQLite and PostgreSQL Database Migrations Background Job Architecture Testing Games platform โ€” current developer reference Bramble Harvest developer tools API Architecture Security and Organization Scoping UI, Icons, and Documentation Assets Blackcap-Safe Emoji Support Chat Architecture Extending Support Chat Support Chat Model Benchmark Documentation Standards Terminology

โš ๏ธ Troubleshoot Blackcap

โš ๏ธ Troubleshooting Licensing Troubleshooting Deployment Troubleshooting Display Troubleshooting Recipe Import Troubleshooting ๐Ÿค– AI Troubleshooting Backup Troubleshooting Database Troubleshooting Diagnostic Organization Clones Support Chat

๐Ÿงฑ Technology, Administration, and Reliability

Audience: Org Admin, Data Admin, System Admin, Deployment Administrator, Developer, Support
Related: Feature Catalog ยท AI Features ยท Database Administration ยท API Tester and Postman ยท Performance and Job Status

Blackcap's everyday features are backed by a substantial administration, diagnostics, data, and deployment foundation. These capabilities are not ordinary household workflows, but they make Blackcap safer to operate, easier to support, and practical to run on either a Raspberry Pi or GCP.

Access remains permission-aware. System-wide diagnostics and repair actions are restricted to System Admins, while organization and data tools remain limited to the roles that need them. The application continues to enforce organization scoping and endpoint permissions even when a technical page is visible.

Architecture at a glance

Blackcap application architecture

Blackcap keeps user interfaces, API clients, background work, persistence, provider integrations, and display delivery behind one permission-aware application model. The same architecture supports a Raspberry Pi appliance/server and a GCP deployment while allowing provider-specific database and infrastructure behavior where it is genuinely required. For implementation boundaries and route ownership, see Application Architecture.

๐Ÿ” Organizations, permissions, and security

  • Organizations are the primary tenant boundary for recipes, meal plans, shopping lists, inventory, displays, configuration, and activity.
  • Role and permission checks distinguish System Admin, Org Admin, Data Admin, contributor/operator, and ordinary-user responsibilities.
  • Internal login supports invitations, password reset, TOTP MFA, recovery codes, trusted browsers, and organization MFA policy.
  • User-owned API Tokens are named, organization-aware credentials with show-once secrets, revocation, access attribution, and retention.
  • CSRF protection, safe external fetch rules, request validation, encrypted or masked secrets, and audit records protect administrative workflows.

๐Ÿ—„๏ธ Database Administration

Database Admin is a provider-aware technical workspace for both SQLite and PostgreSQL deployments. Depending on permission and provider, it includes:

  • resource exploration with explicit relationships and organization context;
  • schema export and provider-aware metadata;
  • saved queries and guarded SQL Console behavior;
  • data-problem detection, maintenance actions, and reconciliation tools;
  • restore and repair diagnostics;
  • database parity and schema-verification support; and
  • controls that keep live writes separate from read-only inspection and audit work.

See Database Administration for the full resource, maintenance, SQL Console, and repair model.

๐Ÿง‘โ€๐Ÿ’ป API Tester and API Tokens

API Tester opens against the current Blackcap instance and uses the registered route inventory rather than a disconnected static list. It supports:

  • role-aware endpoint visibility and execution;
  • the current authentication and organization context;
  • sanitized request and response examples;
  • option and identifier resolution for supported parameters;
  • endpoint testing without requiring separate API software; and
  • Postman export for broader integration development.

API Tester complements personal API Tokens. It does not bypass endpoint permissions, organization scoping, CSRF requirements, or token policy. See API Tester and Postman and API Development.

๐Ÿ–ฅ๏ธ System diagnostics and actions

The System page provides a deeper operational view than the quick About summary. Its capabilities include:

  • application version and build identity;
  • display mode, busy state, project/configuration paths, recipe count, and cloud-backup connection status;
  • detected host, detection source, operating system, architecture, hardware model, container status, and Raspberry Pi capability hints;
  • current uptime and recent reboot history with cautious reason confidence;
  • bounded log viewing from fixed sources with severity/search filters and secret redaction;
  • tracked Direct SQL Audit jobs for finding application code that bypasses the centralized database service;
  • read-only Database Parity / Schema Verification and separately confirmed repair of registered safe additive gaps;
  • e-ink refresh, render, deep-clean, and last-output diagnostics when attached hardware is available; and
  • configuration export without exposing secret values.

Long-running audits are background jobs with queued/running/completed/failed state, progress, duration, and downloadable or inspectable results instead of blocking the page.

๐Ÿ“Š Performance and background jobs

Blackcap records operational timing and job state so administrators can distinguish a slow request, a queued task, a provider delay, and a physical display refresh. Technical visibility includes:

  • request and task duration trends;
  • queue time, execution time, resource snapshots, and slow-request review;
  • render and display-delivery phases;
  • backup, email, purge, external-list, and provider timing;
  • failed, retryable, reviewed, ignored, stale, and stoppable background work; and
  • regression-to-regression performance comparisons.

See Performance and Job Status and Background Jobs.

โ˜๏ธ Backups, restore, and managed maintenance

Blackcap supports local and connected cloud backup destinations, provider-aware backup scope, restore staging, validation, rollback safety, retention, and cache reconstruction. The SQLite database can be included in a Pi backup, while GCP/PostgreSQL deployments keep Cloud SQL backup responsibility at the platform boundary.

Application startup and managed schedules also support idempotent database migrations, periodic backups, display-content refresh, Menu refresh, regression continuation, data purge, GeoIP updates, Letโ€™s Cook watchers, and enabled panel maintenance. See Backups and Restore and Background Jobs and Schedules.

๐Ÿงน Data retention and cleanup

Data Cleanup applies domain-aware retention instead of issuing generic table deletes. Administrators can use dry-run and real-run workflows for generated artifacts, completed jobs, audit history, display assignment batches, recipe-share history, Letโ€™s Cook detail/summary records, restore staging, and other bounded operational data.

Retention rules preserve active dependencies and organization boundaries. See Data Retention and Purge.

๐Ÿงช Regression testing and safe diagnostics

Blackcap includes an administrative regression harness for immediate, scheduled, resumable, and diagnostic-clone runs. Coverage can include role behavior, integrations, display assignment, database/service checks, and the same Direct SQL Audit and Database Parity / Schema Verification jobs exposed on System.

Diagnostic clones allow isolated reproduction without modifying the source organization. See Regression Testing and Diagnostic Clones.

๐Ÿ“œ Audit, access, and support visibility

Technical administration also includes activity history, login and API Token access, display access breadth, voice activity, configuration changes, support-request diagnostics, country-level GeoIP lookup, and privacy-conscious instance reporting. These surfaces are designed to support troubleshooting without exposing raw secrets or unnecessary personal data.

See Audit, Access Activity, and Logging, GeoIP and Access Location, Support Requests, and Instance Reporting.

๐Ÿš€ Deployment foundation

Blackcap maintains two primary server paths:

  • Raspberry Pi: SQLite by default, optional attached e-ink hardware, stunnel TLS, systemd services, managed schedules, and optional Remote Pi Client behavior.
  • GCP: Compute Engine, Cloud SQL PostgreSQL, Cloud SQL Auth Proxy, Gunicorn, Nginx, HTTPS certificates, managed services, and browser or remote-client display delivery.

Customer deployments can also be delivered through Microwave Pie Packages. A Package is associated with one Microwave Pie License and one intended installation, while the reusable Application Release behind it can be either Source / uncompiled or Compiled. Both package formats install immutable release provenance including the exact full Git SHA, deployment mode, platform, Package/Release references, and the application version. The signed License remains the application-use entitlement; the Package controls delivery/provenance and does not replace licensing.

Package-managed installations expose System โ†’ Blackcap Updates and a package-only Configuration โ†’ Platform โ†’ Updates policy to System Admins. Automatic checking can surface Update Available without downloading anything, and automatic checking by itself never forces an update. The policy supports Manual-only checks or heartbeat-driven Automatic checks. With Automatic check selected, an additional opt-in can automatically apply an approved forward update when the Blackcap service restarts; Blackcap performs one fresh startup check, verifies/prepares the package, and hands activation to the existing independent updater. Automatic downgrade is prohibited. UI-driven Check โ†’ Prepare โ†’ Apply Update and Restart, live progress, Update History, and a locally retained Previous known-good release remain available. Source/unmanaged installations expose none of this update machinery. Source packages stay Source and Compiled packages stay Compiled through the workflow.

Source/unmanaged development installations expose a dedicated System โ†’ Package Review panel immediately below the Blackcap version panel. Package Review is deliberately unavailable in packaged/immutable installations. A System Admin can manually compare the exact Python pins already declared in requirements.txt and requirements-cloud.txt with the latest stable PyPI releases compatible with the Python runtime performing the review. Blackcap also walks PyPI dependency metadata, including transitive dependency metadata within a bounded review graph, to calculate a Compatible Target for each exact pin. This prevents Select All from blindly pinning a dependency to a newer release that conflicts with another reviewed package (for example, a dependency whose parent package still requires an older major line). When the currently pinned version is itself incompatible with the reviewed dependency set, Package Review can surface a Dependency repair target that is lower than the current pin. Releases that cannot be dependency-verified or are blocked by unsatisfied constraints are excluded from Select All. Shared dependencies are presented once with Local + Cloud scope; local-only and cloud-only packages retain their narrower scope. Major-version changes are called out explicitly. Range-managed requirements are informational and are never rewritten automatically. The Package Review dialog keeps its title and Close action anchored while the package table scrolls, so maintenance actions remain accessible during long reviews.

Selecting an exact-pinned update changes only the requirement files in which that package is already declared, and writes the reviewed Compatible Target rather than blindly writing the absolute latest release. For example, updating OpenAI updates both requirements.txt and requirements-cloud.txt, while a Raspberry Pi/local-only dependency changes only requirements.txt. Select All selects every verified compatible update/repair currently shown. Update Selected Requirements edits the development working tree but intentionally does not run pip and does not perform any Git operation. Install Pending Packages is a separate explicit action that gathers the exact-pinned packages whose installed versions do not match the current runtime requirements and installs a bounded batch with direct targets such as python -m pip install --upgrade "openai==3.19.0". Intermediate bounded batches may temporarily be dependency-inconsistent, so pip check is deferred until the final requirements mismatch has been installed. The default batch maximum is eight direct packages and can be adjusted for a source environment with BLACKCAP_PACKAGE_REVIEW_MAX_INSTALL_PACKAGES (clamped to 1โ€“20). Recently changed requirement pins are installed first, and interrupted installs can be resumed because Blackcap recalculates remaining mismatches from the active environment. This keeps normal Package Review maintenance from asking pip to resolve the entire requirements file on resource-constrained hosts. When a bounded install updates Playwright itself, Package Review also runs the matching playwright install chromium post-install step so the Python package and managed Chromium revision remain synchronized.

Source/unmanaged systemd installations also expose Copy Full Reconcile Commands for deliberate full-environment maintenance. Blackcap builds the copied shell commands from the current environment: the active Python executable, application checkout, local-vs-cloud requirements file, detected primary Blackcap systemd service, and active companion application services. The command block stops the companion/application services to release memory, compares the current Python environment with every active top-level requirement, and installs only unsatisfied requirements as direct pip install --upgrade targets in bounded batches (four by default, configurable with BLACKCAP_PACKAGE_REVIEW_RECONCILE_BATCH_SIZE, clamped to 1โ€“20). It never hands the entire requirements graph to one pip install -r resolver transaction. After no mismatches remain, the helper verifies every active requirement again, synchronizes managed Chromium when Playwright is present, runs pip check, and restarts the detected services even when reconciliation returns an error. The copied command runs inside a subshell so a reconciliation failure does not log the administrator out of the host shell. Packaged/immutable installations do not expose Package Review or this command path. Blackcap never executes this stop/reconcile/restart sequence from the web request itself; the administrator copies it and runs it in a host shell.

Compiled packaged releases consume requirements-cloud.txt only at build time. The compiled build writes python-dependencies.json into the immutable release with the direct pins plus resolved runtime dependency versions. Packaged System diagnostics can display that provenance, but Package Review remains disabled and no target installation performs package upgrades in place.

The application uses a centralized database service, provider-aware repositories, organization scoping, idempotent migrations, and shared background-job infrastructure so the deployment paths remain behaviorally aligned. See Platform Stacks and Raspberry Pi Hardware, Packaged Distribution, and Application Updates.

๐Ÿ’พ Instance storage visibility

Normal authenticated instance reports include aggregate capacity for the filesystem containing Blackcap. Microwave Pie's software delivery and instance management service can therefore show total disk space, percentage used, and low-available-space fleet filters without inspecting file names or customer content. This telemetry follows the normal instance-report cadence and is advisory; it does not force cleanup or an application update.

More information

On this page