The utility bay in your Mac's notch.

Nodebay is a native, local-first macOS utility bay for MacBook displays with a physical notch and external displays with a virtual top-center notch. It combines media controls, a persistent file shelf, safe file stacks, document conversion, local media downloads, image-copy compression, calendar tools, system HUD replacement, and display-aware placement.

Nodebay is based on Boring Notch at exact commit 44dd999f70493da48209c99e9f873c47f2e55c83. The original project and contributors remain credited. Nodebay is GPL-3.0 software and is not affiliated with or endorsed by Microsoft, YouTube, ImageOptim, Spotify, Apple, or the other service and engine providers it can work with.

Created by Kian Konrad Tajbakhsh.

Copy the setup prompt into your agent's chat. No placeholders need editing. Use an agent with access to your Mac; it will check compatibility, download and verify the installer, preserve existing settings, and guide any permissions or configuration you need to complete yourself.

Nodebay 1.2.2 (29) adds display, hover, HUD, Markdown preview, and shelf-drop improvements on top of the 1.2.1 media and updater release. It includes optional Quick Chat, available-source media tabs, clearer API-key setup and message bubbles that fit their text. It also includes file-drawer fixes and an optional, separately installed Longhaul companion. Apple Silicon and macOS 15 or later are required. Signed in-app updates provide manual checks and optional automatic downloads; existing 1.2.0 users need one Homebrew or manual upgrade. Quick Chat defaults to Off; API billing is separate from ChatGPT subscriptions.

Download the signed release from GitHub Releases or install through the official Homebrew tap. See the verification matrix for completed checks and remaining UI/hardware coverage. The optional Browser Media Bridge requires explicit local installation and is never silently enabled.

The current local source adds a solid/glass background preference (solid by default), more consistent Markdown spacing, clearer table grids and locally rendered Mermaid diagrams. See Markdown preview.

Quick Notes adds local clipboard-to-Markdown creation. Verification separates automated coverage from pending physical hover-paste checks.

STL Repair adds conservative local model-copy repair through the separately installed Blender 5.0.1 companion. Verification and limitations distinguish mesh checks, slicer imports and unperformed physical print tests.

Native Markdown Quick Look renders .md and .markdown in Finder with a transparent, selectable native text view, including with Nodebay quit. Screenshots and verification.

The settings screenshots below are historical captures from earlier Nodebay builds, not evidence of the current release version or complete UI verification. Current Markdown preview comparisons are linked above. The repository does not use inherited Boring Notch screenshots. Browser-tab screenshots will be added only after an explicit Chrome installation and end-to-end UI verification pass.

Local engines and conversion	Downloads and safe image copies

Displays, media, shelf, and attribution

The About 1.1.0 capture above and Quick Notes settings are from the signed 1.1.0 candidate. Other settings captures are historical, as noted above.

The following capabilities are implemented in the current source. Automated checks cover the safety and processing contracts described below. Hardware-dependent and final end-to-end UI checks that have not been rerun are explicitly listed as pending in the release verification matrix; they are not claimed as release-verified.

• Native notch UI on the built-in display and a virtual notch on external displays
• Explicit built-in, selected, main, pointer-active, and all-display placement modes
• Persistent shelf references with security-scoped bookmarks
• Persistent named File Stacks with reorder, preview, dissolve, and multi-file Finder drag
• Space-bar Quick Look, context menus, reference-only shelf removal and Undo
• Quick Notes: explicit paste or a native editor creates persistent Markdown locally; physical hover-paste and destination-app verification remain pending
• STL Repair: conservative copy-first repair through separately installed Blender, with partial-result reports; not a guarantee of watertight or printable geometry
• Markdown Quick Look extension: selectable native Finder previews, including when Nodebay is quit; transparent content preserves the system background
• Local conversion through unmodified Microsoft MarkItDown 0.1.7
• Batch conversion into a separate Markdown result stack with progress, cancellation, partial success, and aggregate errors
• Local yt-dlp downloads with automatic audio-or-video selection, one-click MP4/MP3 overrides, playlist item classification, and optional FFmpeg processing
• Copy-first ImageOptim integration that never sends an original file to ImageOptim
• Local MP4 video compression into separate H.264/AAC copies, with cancellation and size comparisons
• Bounded video-to-GIF conversion for short MP4, MOV, and M4V files
• Independent Apple Music, Spotify, YouTube Music, and system Now Playing source state with an explicit active control target
• Optional independent Chrome tab sources for playable YouTube and YouTube Music tabs through a local first-party bridge
• Provider-registry settings for engines, converters, diagnostics, versions, privacy behavior, license links, and safe fixed-package Homebrew setup
• A real five-band equalizer for local shelf audio, Spotify, QuickTime Player and identified Chrome audio; external apps require System Audio Recording permission on each Mac. Apple Music and unidentified System Now Playing sources remain unsupported.
• XPC-isolated engine execution with structured arguments, strict executable allowlisting, bounded logs, timeouts, and cancellation
• Quick Chat provides temporary conversations through an explicitly selected OpenAI provider, with compact message bubbles that fit their text and optional separately consented Knowledge Folder excerpts
• an optional Longhaul companion shows acknowledged automation state; it requires a separate compatible app and explicit pairing, and no public Longhaul installer is available

Nodebay never overwrites, moves, modifies, or deletes an original shelf file.

• Removing a tile removes only Nodebay's reference and supports Undo.
• Dissolving a stack preserves every member reference.
• Markdown conversion creates a collision-safe, persistent .md copy in Nodebay-managed storage.
• MP4 compression and video-to-GIF conversion create separate outputs and never modify the source video.
• Image compression first creates a collision-safe copy and passes only that copy to ImageOptim.
• In the current source, new downloads remain in Nodebay's persistent file drawer until exported by drag; original files are preserved.
• Generated files remain regular file URLs that can be dragged into Finder or another app.

Document conversion, image compression, file and stack management, and media processing run locally. The Quick Notes, STL Repair and Markdown preview features also process locally. Quick Notes reads the clipboard only after an explicit action; the preview never loads remote images or resources. Nodebay has no analytics endpoint, proxy, download server, or Nodebay cloud account.

Network access is used only by features that inherently need it: yt-dlp connects directly to the URL selected by the user, optional lyrics query LRCLIB, and playback artwork may be loaded from the source-provided URL. Browser-cookie access is disabled by default. The optional Chrome bridge uses native messaging and loopback only; it does not send browser media metadata to a server.

Quick Chat is off by default. Submitted questions and temporary conversation context go to OpenAI through the selected provider. OpenAI API mode uses a key stored in macOS Keychain and separate API billing; a ChatGPT subscription does not provide API credit. Knowledge Folder passages are included only after separate cloud-excerpt consent and when enabled for the question. Nodebay keeps its transcript in memory and requests store: false for API responses; clearing local chat does not promise provider-wide deletion.

See PRIVACY.md for the complete network and permissions disclosure.

Exact Swift package revisions, licenses, source URLs, companion status, the FFmpeg build configuration, and full texts are recorded in THIRD_PARTY_NOTICES.md, THIRD_PARTY_LICENSES_MARKITDOWN, and third_party/nodebay-components.json.

• Apple Silicon Mac
• macOS 15 Sequoia or later. The current MediaRemoteAdapter foundation binary is built with a macOS 15.0 minimum.
• ImageOptim installed separately for image compression
• yt-dlp and FFmpeg installed separately for media downloads and conversion
• Blender 5.0.1 installed separately for the STL Repair feature; it is not bundled or installed by the Nodebay cask
• For Quick Chat: an explicitly selected provider, either a supported signed Codex CLI with its existing sign-in or an OpenAI API key and usable API billing; neither provider is required for the base app

Companion installation for development:

brew install yt-dlp ffmpeg

Download ImageOptim from its official website.

Install the signed and notarized Apple Silicon release with Homebrew:

brew tap Kian-hdr/nodebay
brew trust --cask Kian-hdr/nodebay/nodebay
brew install --cask Kian-hdr/nodebay/nodebay

Homebrew 6 requires the one-time brew trust command for casks from third-party taps. It trusts only the Nodebay cask, not every package in the tap.

See Homebrew installation and the release packaging details.

For manual installation, download the Apple Silicon DMG from Nodebay Releases, verify the published SHA-256 checksum, open it, and drag Nodebay.app to Applications.

Prerequisites: Xcode 26 or later, a Python 3 interpreter for build tooling, and Apple Silicon. The runtime builder downloads and verifies the pinned Python.org installer, extracts an arm64 interpreter into a private build cache, and leaves system Python unchanged.

git clone https://github.com/Kian-hdr/nodebay.git
cd nodebay
git switch dev
./scripts/build_markitdown_runtime.sh
./scripts/test_markitdown_runtime.sh
./scripts/test_downloader_local.sh
./scripts/test_imageoptim_local.sh
xcodebuild \
  -project boringNotch.xcodeproj \
  -scheme boringNotch \
  -configuration Debug \
  -destination 'platform=macOS,arch=arm64' \
  build

The bundled MarkItDown runtime is generated and excluded from Git. Its full dependency lock and notices are reproducible from the checked-in scripts and requirements.

./scripts/package_homebrew_arm64.sh

The script builds the runtime, executes real PDF and DOCX fixtures, performs a clean Release build, stages Nodebay.app, installs license and privacy records, verifies arm64 executables and the staged signature, and produces a ZIP plus SHA-256 under build/nodebay-homebrew-arm64-release/.

Public distribution still requires Developer ID signing and notarization. An ad-hoc signature is suitable only for local verification.

For a Developer ID package, use the exact identity and team already installed in the signing keychain:

SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
DEVELOPMENT_TEAM="TEAMID" \
./scripts/package_homebrew_arm64.sh

The script asks Xcode to sign the app and XPC service with their target entitlements, signs every bundled MarkItDown Mach-O component with the same Developer ID and hardened runtime, then reseals the final app after installing notices. Notarization is a separate explicit release step.

Verify the resulting archive before notarization:

EXPECTED_VERSION=1.2.2 EXPECTED_BUILD=29 \
./scripts/verify_release_artifact.sh build/nodebay-homebrew-arm64-release/Nodebay-1.2.2-arm64.zip

After notarization and stapling, set REQUIRE_NOTARIZED=1 to add Gatekeeper and staple validation.

• Files and folders: persistent shelf references and chosen output locations
• Accessibility: optional system HUD replacement and related controls
• Apple Events: Apple Music, Spotify and QuickTime control
• Calendar: optional calendar and reminders features
• Camera and microphone or audio capture: optional mirror, camera, and waveform features
• Network client: direct downloads, optional lyrics, artwork, local media companions, and explicitly enabled Quick Chat
• Local networking: the existing local YouTube Music companion integration
• Chrome extension: optional native messaging and site access limited to YouTube and YouTube Music

Nodebay keeps the legacy theboringteam.boringnotch bundle identifier in the first migration-safe build so existing preferences, bookmarks, saved shelf state, and Accessibility authorization remain usable. The user-visible product and release artifacts are Nodebay. A future bundle-identifier change must ship with a signed, tested migration.

• Individual browser-tab control currently supports explicitly permitted Google Chrome tabs on www.youtube.com and music.youtube.com. Other browsers and sites fall back to system Now Playing.
• Chrome requires the bundled extension to be loaded explicitly; Nodebay cannot silently install or enable it.
• ImageOptim behavior follows the installed app's preferences. Nodebay reports that status and always protects the source through a copy-first workflow.
• Physical multi-monitor, clamshell, Spaces, full-screen, Mission Control, and Stage Manager regression checks require the final manual hardware test pass.
• Signed in-app updates are configured for Nodebay's own GitHub feed. Choose automatic checks/downloads or use Check for Updates in About Nodebay. Existing 1.2.0 installations need one final manual or Homebrew upgrade; see update setup.
• Downloader site support depends on the separately installed yt-dlp version and the source service. Automatic mode falls back to video when structured metadata is ambiguous; it does not identify songs from titles alone.
• Quick Notes accepts up to 1 MiB; rich text falls back to plain text when conversion is unreliable. Its physical hover-paste workflow still needs verification.
• STL Repair does not detect or repair self-intersections and cannot guarantee printability. Inspect every result before manufacturing.
• Markdown preview accepts files up to 2 MiB; larger formatted input uses bounded plain-text fallback. Images appear as alt text, links can be copied but do not navigate, and syntax emphasis is intentionally restrained. Finder preview has been exercised on macOS 26.6.2, not every supported macOS version.
• Quick Chat delivers complete replies, not token streaming. Native API connection and synthetic chat tests passed. The historical App Server isolation issue concerns that disabled streaming route; final release validation is tracked separately in the verification matrix. Provider retention is separate from Nodebay's temporary local transcript.
• The optional Longhaul integration does not install Longhaul, pair automatically, or guarantee an active sleep assertion, closed-lid operation or an unlocked desktop. Its sun icon means automatic protection is enabled, not that a job is currently protected.

The original Nodebay icon was authored as layered artwork and assembled in Apple Icon Composer. Editable source and all exported appearances are under Design/NodebayIcon. Production sizes are generated by scripts/generate_nodebay_appicon_assets.sh.

Nodebay is licensed under GPL-3.0. Modified binary distributions must preserve notices and provide corresponding source and reproducible build instructions as required by the license.

• Based on Boring Notch, GPL-3.0
• Document conversion by Microsoft MarkItDown, MIT
• Download integration for yt-dlp, distribution-dependent licensing documented in notices
• Media processing through FFmpeg, exact build-license result documented in notices
• Optional compression through separately installed ImageOptim

Nodebay does not fork or modify MarkItDown, yt-dlp, FFmpeg, or ImageOptim.

Read CONTRIBUTING.md before opening a pull request. Use SUPPORT.md for privacy-safe reporting guidance and SECURITY.md for private vulnerability disclosure.

Nodebay is an independent project. Questions about the Boring Notch foundation should be directed to its upstream repository.

• Installation, Homebrew, and permissions
• Privacy and security, architecture, and troubleshooting
• Building from source and reproducible release process
• Migration from Boring Notch, acknowledgements, and changelog
• Security reports, issue reporting, and releases