Chapter 18
Keyboard, URL Scheme & Troubleshooting
The fast paths and the safety nets: shortcuts, deep links, the app's own logs, and a calm answer for the handful of things that go wrong.
This closing chapter is the reference you reach for when you already know what FrontierStack does and just want to do it faster — or when something is red and you want the shortest route to green. It collects the keyboard shortcuts, the frontierstack:// URL scheme, where the app keeps its own logs, and a symptom-to-fix table for the problems that actually come up. None of it is essential reading; all of it saves you time.
18.1Keyboard shortcuts
FrontierStack is a native Mac app, so the system shortcuts you already know — ⌘W to close a window, ⌘, for Settings, ⌘Q to quit — all work. On top of those, the app adds a small, deliberate set of its own. The philosophy is restraint: most actions live on clearly labelled buttons, and almost every dialog follows the Mac convention that Return confirms and Esc cancels, so you rarely need to memorise anything.
| Shortcut | Does | Menu equivalent |
|---|---|---|
| ⌘F | Open the Search palette — find any service, tool, pane or action by name and jump straight to it. | Toolbar magnifying-glass button |
| ⌘? | Open the in-app Help window. | Help ▸ FrontierStack Help |
| ⌘⌥⇧W | Close all floating palettes at once. | Palettes ▸ Close All Palettes |
| Return | Confirm the default button in any sheet (Save, OK, Add, Install…). | The highlighted button |
| Esc | Cancel or dismiss the current sheet or palette. | Cancel / Done button |
The menu bar carries the rest of the app's reach: dedicated Services, Locations, Monitors, Presets and Palettes menus let you switch a service, change location, toggle a monitor, apply a saved preset or pop out a floating palette without leaving the keyboard. Because these are real menu commands, macOS lets you assign your own shortcut to any of them under System Settings ▸ Keyboard ▸ Keyboard Shortcuts ▸ App Shortcuts — add FrontierStack, type the menu item's exact name, and pick a key.
18.2The frontierstack:// URL scheme
FrontierStack registers the frontierstack:// URL scheme, which deep-links straight to any pane, server or service. Opening such a URL brings the app to the front and navigates — expanding the right sidebar group and scrolling to the destination. This is how a link in a note, a Shortcuts action, or a line in a script can send you (or a teammate) to exactly the right screen.
From Terminal you trigger one with open; from Shortcuts use the Open URLs action; in a note or web page it is an ordinary link. The forms are:
| URL | Goes to |
|---|---|
frontierstack://server/<name-or-id> | That fleet host's pane (falls back to Local Health if unknown). |
frontierstack://website/<domain> | The Sites pane. |
frontierstack://container/<name> | The Docker pane. |
frontierstack://pane/<Name> | Any pane by its display name, e.g. pane/Security, pane/Apache, pane/Alerts. Spaces are URL-encoded (%20). |
frontierstack://service/<catalog id> | A catalog service by its id. |
frontierstack://kube/<context> | A Kubernetes context (or the Clusters pane with no argument). |
frontierstack://security · ://alerts · ://health | Shortcuts to the Security, Alerts and Local Health panes. |
frontierstack://device/<id> · ://wifi/<ssid> · ://zone/<id> | A discovered device, a Wi-Fi network, a Cloudflare zone. |
frontierstack://open?sel=<raw> | The exact escape hatch: an internal selection value that round-trips precisely. |
A few worked examples:
open "frontierstack://pane/Security"
open "frontierstack://server/mac-mini-office"
open "frontierstack://website/example.com"Deep links are the connective tissue of automation in FrontierStack. A preset can include a link that jumps to its dashboard; a runbook in Notes can link each step to the pane where you carry it out; an alert message can point at the failing service. The same scheme also names two read-only resources for AI — frontierstack://capabilities and frontierstack://health — that the MCP server exposes (see Chapter 14).
frontierstack:// URL brings the window forward so you can unlock, but it will not navigate — external automation cannot move the app around behind the lock screen.18.3Reading the app's own logs
When you need to know what FrontierStack itself did — not what a service did, but the app — there are three places to look, in increasing depth.
- The Change Log (Audit). The Logs pane includes a Change Log that records every setting and configuration change with the responsible actor: User, the AI Harness, the Web control panel, MCP, or Automation. If a service goes down, this tells you exactly what touched it and who or what was responsible — the fastest first question in any incident.
- The in-app console. Installs and shell commands run in a real terminal window inside the app (a PTY, so password prompts and y/n questions work), streaming live output. Because the app knows when the command finishes, it refreshes the pane that launched it. You can export a console transcript from its actions bar. Theme it under Terminal Style in Overview.
- The log files. FrontierStack writes its own log to
~/Library/Logs/FrontierStack. Open that folder in Finder, or read it in Console.app, when you want the raw record — it is the most detailed account of what the app was doing. The Auto-export feature (Overview ▸ Settings) can copy these logs, your change-log and settings backups to a folder on a schedule.
read_log tool accepts a source of "frontierstack" to tail ~/Library/Logs/FrontierStack, "os" for the system log, or a service name like "nginx" or "postfix". On a linked server it reads over SSH, and output is capped and secret-redacted before any of it reaches a cloud model (Chapter 13).18.4Common problems & fixes
Most trouble in FrontierStack is one of a small, familiar set, and the app usually offers the fix as a button rather than a chore. The table below maps the symptom you see to the shortest route back to green.
| Symptom | Likely cause | Fix |
|---|---|---|
| A service won't start. | A port is already in use, the binary isn't installed, or the config is invalid. | Open the service's pane and read the status detail. Use Ports in Use to find a conflict; install or repair via Homebrew; for web servers, validate the config before reloading. The AI Administrator's repair_service can diagnose and fix common cases on your approval. |
| A linked server's status dot is red: "Permission denied (publickey)". | The server was reinstalled, its host key changed, or the app's SSH key was never installed. | Run Repair SSH access (the AI's repair_ssh_access tool, Chapter 8). It clears the stale host key and re-installs the app's managed key using a one-time login password stored as a vault secret — the password is read locally and never sent to the model. The dot turns green on success. |
| Alerts aren't arriving. | A channel is misconfigured: a wrong token, an unverified sender, a bad webhook. | Open Alerts. A per-send Delivery Errors section lists exactly which channel failed and why; fix the credential and Clear delivery errors. Send a test to confirm before relying on it (Chapter 11). |
| The AI refuses an action. | It is read-only by default, or a specific server toggle is off. | Enable Allow changes (and Allow scripts if it wants to run one) on the AI Administrator, or the relevant per-server toggle. The refusal message names the exact setting — see below. |
| Homebrew is missing. | The package manager many services rely on isn't installed. | Open the Homebrew pane (Overview). The app can install Homebrew for you and then offers one-click installs of formulae from each service's pane. |
| A certificate isn't trusted. | A self-signed or local certificate the system doesn't yet trust. | For local development, issue with mkcert, which installs a trusted local CA; for public sites use Let's Encrypt. Manage both in Certificates and the Sites ▸ TLS tab (Chapter 7, Chapter 10). |
18.5MCP onboarding & the actionable refusal
The first time the app sees a chance to, it asks — once — whether you would like to start the MCP server so an outside AI tool (Claude Code, Cursor, Claude Desktop) can drive FrontierStack. The prompt explains the model plainly: the server is localhost-only, token-protected, and read-only by default. Start MCP server turns it on; an optional toggle on the same sheet lets you allow changes there and then; Not now simply remembers that you were asked. The server stays off until you choose otherwise (Chapter 14).
This connects to a small design idea that runs through the whole app. When any external surface — the MCP server, an App Shortcut, the AI — refuses to make a change, it does not just say "no". It tells you why, and where to turn it on. A refusal might read: changes are off — enable them in the AI Administrator; or, for MCP, enable it in Remote Control & Lock ▸ MCP. The reason it points you to the app rather than offering to flip the switch itself is the core of the trust model: a remote agent can ask, but only you, at this Mac, can grant. A refusal is therefore never a dead end — it is a signpost to the one toggle that unblocks you.
18.6Getting help
Three resources back you up, in order of immediacy.
- The in-app Help window. Press ⌘? or choose Help ▸ FrontierStack Help for the built-in documentation, which leads with the AI features and covers every pane and service. Many panes also carry a ? button that opens Help at the matching section. Help's "Open in app" links jump you straight to the pane they describe — Help stays open while the main window comes forward.
- The website Help & FAQ. frontierstack.app/help mirrors the in-app documentation in a browsable form, and the FAQ answers the questions new users ask most. Migration guides live at frontierstack.app/migrate.
- Support & feedback. At frontierstack.app/support two short forms reach the team directly: a support request (include your macOS version) when something is wrong, and a feature request for what would make FrontierStack better. Both go straight to the people who build the app.
That brings the manual to a close. You have met FrontierStack as a control panel, a monitoring system and an AI administrator; you have stood up the web stack, linked a fleet, hardened the perimeter, wired up alerts, and handed the keys — carefully, on your terms — to an assistant that can see and fix your servers. The rest is doing. Keep ⌘? close for the in-app Help, visit frontierstack.app when you want the latest, and tell us at Support what you would like next. Thank you for running your servers with FrontierStack.
FrontierStack User Manual · Version 1.0.0 · Chapter 18