FrontKiosk Documentation

Getting Started

System Requirements

FrontKiosk requires macOS 14.0 or later. It is built with Swift and SwiftUI. No additional dependencies are required.

First Launch

When you first launch FrontKiosk, you will see:

• A welcome overlay filling the screen with a customizable title, message, and logo
• A custom dock at the bottom (or side) with default applications: Safari, Maps, Photos, and Music
• A menu bar icon (two horizontal lines in a grid) in the top-right area of your screen

By default, kiosk mode is off. Users can switch between apps freely. Enable kiosk mode when you want to restrict access to only the apps in your dock.

Accessing Settings

Click the menu bar icon to open the FrontKiosk menu. From there you can:

• Enable/Disable kiosk mode — Toggle between locked and unlocked states
• Open Settings... — Configure applications, appearance, security, and license
• Open About... — View version, check for updates, and access support links
• Quit — Exit the application (if not hidden by security settings)

Menu Bar & Quick Access

FrontKiosk runs as a menu bar application. It does not appear in the Dock by default. The menu bar icon provides quick access to all main functions.

If you have enabled an admin password, you will be prompted to enter it when you try to toggle kiosk mode or open settings. The password dialog auto-closes after 30 seconds if no action is taken.

General Settings

Applications in the Dock

This section defines which apps appear in the custom dock. Only these apps will be available when kiosk mode is on.

• Add App... — Opens a file picker to select one or more applications (.app bundles). You can add apps from /Applications, /System/Applications, or any other location.
• Remove — Click the red minus button next to an app to remove it from the dock.
• Reorder — Drag and drop items in the list to change the order they appear in the dock.

You cannot add or remove apps while kiosk mode is active. Disable kiosk mode first, make your changes, then re-enable.

Activation

Enable Kiosk Mode — When on, the system is locked down:

• Only approved apps (from the dock) can be used
• If a user switches to an unapproved app (e.g. Finder), FrontKiosk immediately brings itself back to the front
• Optional system restrictions (keyboard shortcuts, menu bar, etc.) are applied based on Security settings

Launch

Start automatically at login — When enabled, FrontKiosk launches when the user logs in. This uses macOS SMAppService (Service Management framework) and requires no additional configuration.

Appearance Settings

Welcome Screen

The welcome screen is the main overlay shown when FrontKiosk is active. You can customize:

• Title — Main heading (e.g. "Welcome to this kiosk")
• Message — Subtitle or instructions (e.g. "Select an application below...")
• Welcome Title Color — Color picker for the title text
• Welcome Message Color — Color picker for the message text
• Logo — Optional custom image (PNG, JPG, etc.). If not set, the FrontKiosk app icon is used.

Background Type

Choose how the overlay background looks:

• Transparent — A frosted glass effect that subtly blurs and darkens the content behind. Best for a modern look.
• Custom Color — Solid or gradient background:
  • Solid — Single color
  • Gradient — Two colors with configurable direction (Top to Bottom, Left to Right, Diagonal)
• Custom Image — Use an image file as the full-screen background.

Dock Options

The custom dock can be heavily customized:

You can also drag and drop apps directly onto the dock from Finder to add them, and reorder them by dragging. Right-click an icon for a context menu to remove it (when kiosk mode is off).

Security Settings

Authentication

Require Admin Password — When enabled, anyone trying to open Settings, toggle kiosk mode, or perform other protected actions must enter the admin password.

When you first enable this, you will be asked to set a password. You must enter it twice (password and confirmation) to avoid typos. You can change the password later with Change Password....

Note: Password protection is only available in the licensed version. In Trial Mode, this option is disabled.

System Restrictions

When kiosk mode is enabled, you can block specific keyboard shortcuts and system features. These options only take effect while kiosk mode is on:

Blocking these shortcuts requires Accessibility permission. FrontKiosk uses a low-level event tap to intercept key events before they reach the system.

Accessibility Settings

For keyboard shortcut blocking to work, FrontKiosk must have Accessibility permission in System Settings:

1. Open System Settings → Privacy & Security → Accessibility
2. Add FrontKiosk if it is not listed, or enable the checkbox next to it
3. You may need to quit and relaunch FrontKiosk

The Settings window shows whether access is granted. Use Grant Access... to open the relevant System Settings pane directly.

License & Activation

FrontKiosk offers a Trial Mode and a Licensed Version.

Trial Mode

In Trial Mode, most features work. Some limitations apply:

• Password protection is disabled
• Hide Quit Menu Item cannot be enabled
• A trial banner may be shown on the overlay

Licensed Version

To activate a full license:

1. Enter your Email Address (as used when purchasing)
2. Enter your License Key
3. Click Validate License

Validation is performed online against xProline's license server. If successful, the app switches to Licensed mode and all restrictions are removed.

Start Automatically at Login

This option uses macOS SMAppService to register FrontKiosk as a login item. No LaunchAgents or LaunchDaemons are used. The setting is stored in the app sandbox and persists across launches.

Technical Details

Architecture

FrontKiosk is built with Swift and SwiftUI. It uses:

Window Management

FrontKiosk uses several custom window types:

• OverlayWindow — Full-screen, borderless, covers the primary display. Uses mainMenu - 1 level when intercepting mouse, or -1 when allowing click-through to allowed apps.
• DockWindow — Borderless, always on top (mainMenu + 1). Positioned at screen edges based on user preferences.
• FloatingWindow — For Settings, About, and password dialogs. Uses mainMenu + 2 to appear above overlay and dock.

Windows are reused rather than recreated when showing/hiding, to avoid flicker and improve performance.

Kiosk Mode Behavior

When kiosk mode is enabled:

• NSApplication.PresentationOptions are applied (hide dock, hide menu bar, disable process switching, etc.)
• An optional Apple Menu Blocker panel covers the Apple menu area
• An event tap intercepts keyboard events to block disabled shortcuts
• A heartbeat timer (every 2 seconds) reapplies kiosk state to handle edge cases

When an allowed app is activated, the overlay becomes click-through and moves to the background. When an unapproved app is activated, FrontKiosk immediately brings itself back to the front.

Data Storage

Preferences (applications, appearance, security options) are stored in UserDefaults under the key FrontKioskPreferences. License information is stored separately. All data is stored within the app's sandbox.

System Dock

An option can auto-hide the system Dock via AppleScript and defaults write. This is separate from the custom dock and is intended to reduce clutter when the kiosk overlay is visible.

Troubleshooting

Keyboard shortcuts are not blocked

Ensure FrontKiosk has Accessibility permission in System Settings → Privacy & Security → Accessibility. If it was recently granted, quit and relaunch the app.

Overlay or dock not visible

Check that no other app is covering the screen. FrontKiosk uses specific window levels; very high-level windows (e.g. some screen savers) might appear above it. Try activating FrontKiosk from the menu bar.

Settings or About window behind overlay

Settings and About use FloatingWindow with a high level. If they appear behind, try clicking the menu bar icon again to bring them forward, or use the Window menu if available.

Apps not launching from dock

Verify the app path is valid (e.g. the .app was not moved or deleted). Re-add the app from Settings if needed. Some system apps may require additional permissions.

Password prompt keeps appearing

Ensure you are entering the correct password. If you forget it, you must clear the stored password (which requires access to the app's preferences or a fresh install). In Trial Mode, password protection is disabled.

Launch at login not working

Verify the option is enabled in Settings. On first enable, macOS may prompt for permission. Ensure FrontKiosk is not blocked by any security software.