Help Guides
Using the Hub on macOS
The Mac app has the same screens, names and order as every other Hub app. This page covers what's specific to the Mac: installing it, the keyboard, windows, where your session is kept, and connecting to a development copy of the API.
Install
Download the latest build from the macOS app's releases, open the disk image, and drag Substratal Hub to Applications. It needs macOS 15 Sequoia or later. Release builds are signed and notarized by Apple, and update themselves.
Until the first notarized release is published, the app is built from source. See the repository's README.
Sign in
The app opens on Sign in. Enter your email and password and press Return. If your account has two-factor authentication on, Two-factor asks for the 6-digit code from your authenticator app, or one of your recovery codes. See Signing in and keeping your account secure.
Your session is kept in the macOS Keychain, on this Mac only, and never synced. The app renews it in the background, so you stay signed in until you sign out, for 30 days without using the app, or for 90 days at most. Signing out ends the session on the server too.
Get around
A sidebar on the left lists every section you can use: Personal, Administration and Developer. You only see what your account has permission for.
Every screen shows its ID (such as USR-01) under the window title. The ? button in the toolbar, or Help → Help for This Screen, opens that screen's page in this help center.
Keyboard shortcuts
Every shortcut is also in a menu, so you can always find it there.
| Shortcut | Goes to | Menu |
|---|---|---|
| ⌘1 … ⌘6 | Home, Inbox, Organizations, Account, Plan & Billing, Settings | Go |
| ⌥⌘1 … ⌥⌘4 | Users, Access, Roles, Audit Log | Go |
| ⌃⌘1 … ⌃⌘4 | Applications, API Keys, Webhooks, Tenant | Go |
| ⌘K | Command palette: find any user, app, key or event | Go |
| Shortcut | Does | Menu |
|---|---|---|
| ⌘N | New window | File |
| ⇧⌘N | New item on this screen (Invite user, New role, Create key…) | File |
| ⌘F | Search this list | Edit |
| ⌘R | Refresh | View |
| ⌃⌘S | Show or hide the sidebar | View |
| ⌥⌘I | Show or hide the inspector | View |
| ⌘C | Copy the selected row's ID | Edit |
| ⌘⌫ | Remove, revoke or suspend the selection (asks first) | Edit |
| ⌘Z | Undo turning access on or off, within 10 seconds | Edit |
| ⇧⌘U | Mark all as read (Inbox) | Edit |
| ⌘↩ / Esc | Submit / cancel a sheet | — |
| Space | Preview the selected row | — |
| ⌘, | Settings | Substratal Hub |
| ⌘? | This help center | Help |
Several windows
Right-click any sidebar item, user, app or role and choose Open in New Window to keep it alongside another screen. Each window keeps its own place, and windows come back where you left them.
Lists and tables
Click, ⇧-click and ⌘-click select rows, and ⌘A selects all. Right-click a selection for its actions; they're the same as the toolbar's. Drag an audit event out of the list to save it as a .json file.
Settings
Substratal Hub → Settings… (⌘,) has two tabs:
- Appearance (Settings): Match System, Light or Dark, and any of the five light and five dark themes. See Themes and appearance.
- Connection: which copy of the Platform API the app talks to. Most people leave this on Production. Developers working on the platform itself can choose Local devserver, the API repository's
make runathttp://localhost:8080. Switching signs you out, and each connection keeps its own session, so a production session is never sent to a development server. When the app is connected to a devserver, Sign in offers Test-mode account.
Update notices
The app is built for one API version. It reads the API's version headers on every response (see API versioning):
- Update available: the API has deprecated this app's version. The banner gives the date it stops working, at least 6 months away. Update the app before then.
- Update required: the API no longer supports this app's version. The app stops calling the API until you update.
Not on the Mac
The Operations console (health, traffic, logs, alarms and cost) is in the web Hub only. It reads monitoring data through a server the native apps can't reach without exposing that data publicly.
Screens in this guide
AUTH-01 · Sign in AUTH-02 · Two-factor challenge SET-01 · Settings — Global GLB-01 · Command palette GLB-03 · System states