Toolsquare Mac App

Setup and administration

Installing, configuring and running the Toolsquare Mac App on macOS.

What it is

The Toolsquare Mac App keeps a shared workshop Mac behind a full-screen lock until a user is authorised at the Toolsquare hardware unit. The unit is the source of truth: the Mac boots locked, stays locked until the unit says otherwise, and re-locks 30 seconds after the unit is unplugged mid-session.

An unlocked session gives normal use of the whole machine. Per-application whitelisting and on-screen safety checklists are Windows-only. The active booking is shown on the lock screen, in the menu bar dropdown, and in a desktop or Notification Center widget.

Requirements

OSmacOS 13 (Ventura) or later. The booking widget needs macOS 14 (Sonoma).
HardwareApple silicon Mac; Intel is not supported. Plus a Toolsquare USB unit.
PrivilegesLocal administrator to install, to approve the USB driver, and to grant Accessibility.
PermissionsAccessibility, so keyboard shortcuts can be blocked while locked. Can be pre-approved by MDM.
SigningThe package and every binary in it are Developer ID signed and notarised, so Gatekeeper accepts them without overrides.

Install and set up

Protection starts when the installer finishes. The lock screen holds off only while the first-run setup window is open, so you can complete the install undisturbed. Submitting that window arms the machine.

  1. Connect the unit by USB.
  2. Run Toolsquare-<version>.pkg. It asks for an administrator password, registers the background daemon, sets the menu bar agent to start at login, and places the uninstaller, the widget host and the driver installer in /Applications. Installing over an older version upgrades in place.
  3. Install the USB driver. Open Install CP210x VCP Driver from /Applications, then approve the Silicon Labs system extension under System Settings → Privacy & Security. Re-plug the unit afterwards.
  4. Grant Accessibility. Open System Settings → Privacy & Security → Accessibility and enable ToolsquareMac. No restart needed.
  5. Complete first-run setup. The setup window asks for the customer name, the bypass PIN and an optional logo.

Verify that the Toolsquare icon appears in the menu bar, that sudo launchctl print system/com.toolsquare.daemon reports the daemon running, and that the menu bar dropdown shows Device with a serial port (typically /dev/tty.TSQR_USBtoUART) rather than Disconnected.

What gets installed

ComponentRuns asResponsible for
ToolsquareDaemonAt boot, as root (com.toolsquare.daemon)Talks to the unit over USB, decides the lock state, and writes status.json.
ToolsquareMacAt login, per user (com.toolsquare.agent)The lock overlay, shortcut blocking, the admin PIN prompt, the menu bar item, and the widget's data.
Toolsquare Widgets/ApplicationsPublishes the booking widget to the macOS widget gallery (macOS 14+).
Toolsquare Uninstaller/Applications, on demandRemoves the app, its settings and its logs.
Install CP210x VCP Driver/Applications, on demandThe signed Silicon Labs driver for the unit's USB-to-serial bridge, which macOS does not drive out of the box.

The agent is a system-wide LaunchAgent, so the lock applies to whichever macOS account signs in. The menu bar item has no Quit option, and launchd restarts the daemon and the agent if either exits.

Settings

All settings are entered once, in the first-run setup window. There is no separate configuration app and no file to hand-edit.

SettingNotes
Customer nameShown on the lock screen when no logo is set.
Bypass PIN4 to 8 digits, entered twice. Unlocks a Mac locally without the unit. Stored as a SHA-256 hash in a root-owned file; it cannot be read back, only replaced.
LogoOptional PNG or PDF, shown on the lock screen. The background shade adapts to it.

Settings are set once. There is no settings screen to change the PIN or the branding later. To change them, run the Toolsquare Uninstaller and reinstall, which brings the setup window back. Settings survive normal version upgrades.

Unlocking without the unit

At the lock screen click Admin… in the bottom-right corner, or press Control+Option+Shift+Command+U, and enter the bypass PIN. The overlay clears for 3 minutes, then the Mac locks itself again. This is an escape hatch for maintenance and for a failed unit, not a way to hand out sessions.

The PIN cannot be recovered. It is stored hashed, so a lost PIN means reinstalling the machine to set a new one, or contacting support for the recovery procedure. Anyone with the PIN can unlock the machine, so keep it to the staff who need it.

Fleet deployment

Silent install

sudo installer -pkg Toolsquare-<version>.pkg -target /

Logs and state

/Library/Application Support/Toolsquare/Logs/Rolling daemon and agent logs. Attach these to support tickets.
/Library/Application Support/Toolsquare/status.jsonLive lock state, unit connection, serial port and booking.
/Library/Application Support/Toolsquare/config.plistCustomer name, PIN hash and logo path. Root-owned, written by the daemon.
Menu bar dropdownApp version, status (Locked, Unlocked, Out of Order, Service not running) and the device connection.
launchctl printsudo launchctl print system/com.toolsquare.daemon for the daemon, launchctl print gui/$(id -u)/com.toolsquare.agent for the agent.

Update and uninstall

To update, run the newer .pkg: it upgrades in place, restarts the daemon and the agent, and keeps your settings.

To uninstall, open Toolsquare Uninstaller from /Applications. It asks for an administrator password, then removes the daemon, the agent, and all settings and logs. Drag Toolsquare Widgets and Install CP210x VCP Driver to the Trash afterwards if you want those gone too.

With the app removed, the Mac is unprotected: nothing shows the lock screen or blocks input.

Troubleshooting

SymptomCheck
Locked even though the user authorised at the unit Re-seat the USB cable: a disconnected unit deliberately holds the lock. The menu bar dropdown should show Device with a serial port. Then read status.json. Allow a few seconds after a unit reboot for it to re-sync.
Unit not detected (Device: Disconnected) Usually the USB driver is missing or its system extension was never approved. Run Install CP210x VCP Driver, clear any pending prompt under System Settings → Privacy & Security, then re-plug the unit and confirm a tty.TSQR device appears in /dev. Otherwise try another cable or port; avoid hubs.
Keyboard shortcuts still work at the lock screen The Accessibility permission is missing. Enable ToolsquareMac under System Settings → Privacy & Security → Accessibility. Without it the overlay still appears and the Dock and menu bar are still hidden, but Command+Q, Spotlight and Force Quit cannot be intercepted.
Toolsquare unit disconnected keeps appearing The Mac keeps losing the serial connection mid-session. Suspect the cable, a USB hub, or the unit's power. The 30-second countdown is deliberate: a Mac that cannot hear its unit re-locks rather than staying open.
Setup window says Daemon not responding The daemon is not running or cannot write its files. Check sudo launchctl print system/com.toolsquare.daemon and the logs. Reinstalling the package re-registers and restarts it.
No Toolsquare icon in the menu bar The agent starts at login, so log out and back in first. Then check launchctl print gui/$(id -u)/com.toolsquare.agent and the agent log. A crowded menu bar can also hide the icon behind the notch.
Booking widget missing from the gallery It needs macOS 14 or later and will not appear at all on macOS 13. On macOS 14+, open Toolsquare Widgets from /Applications once and look again under Edit Widgets…; logging out and back in also refreshes the gallery.

Support

Contact support@toolsquare.io with the app version from the menu bar dropdown, the logs from /Library/Application Support/Toolsquare/Logs/, what the dropdown reports for Status and Device, and what the user did.

© Toolsquare · Mac App setup guide