Keyboard, URL Scheme & Troubleshooting

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.

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.

When several windows or palettes hide one another, choose Palettes › Organize Windows & Palettes. FrontierStack tiles the visible, resizable windows on each connected display independently, using the area outside its menu bar and Dock. Full windows get the main area, floating palettes use a side rail where space permits, and mini palettes remain compact. Windows stay on their current display; confirmation, approval and other temporary panels are not moved. The resulting palette frames are saved with the active Setup like any manual layout.

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:

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).

18.3Reading the app's own logs

The Logs pane reads any machine, not just this Mac: a Machine picker at the top switches to a linked server, whose logs are fetched over SSH — or through its FrontierStack monitor where one is installed, which runs as root and so reaches privileged logs without sudo. The source menu lists the services actually running on the chosen machine first (Apache, Nginx, MySQL, PHP-FPM, PostgreSQL, Redis, Ollama), then any other log files it finds, and finally crash reports and diagnostics — the .ips, .crash and .panic files Console shows, newest first, from both the user and system DiagnosticReports folders.

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.

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.

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 can use FrontierStack. The prompt explains the model plainly: the server is localhost-only 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).

In the MCP pane, Detected AI clients recognizes Amp, Grok, Codex CLI, Cursor, Gemini CLI, Claude Code, Claude Desktop and Xcode. Configure one client, use Set Up Detected, or enable setup at launch. FrontierStack preserves every unrelated MCP entry and installs only its own owner-only bridge; the bearer token remains in Keychain rather than the client’s configuration. Amp setup does not enable its remote thread or terminal features. Network-open MCP is a separate, explicit choice for paired and scoped callers over TLS.

A client reports “connection refused” or fails to start the FrontierStack bridge (~/Library/Application Support/FrontierStack/mcp-bridge). The bridge itself is fine; nothing was answering on the MCP port because FrontierStack was closed and the background service wasn’t running. The bridge now starts FrontierStack hidden on the first call and waits for it, so the first request after a restart can take up to a minute. If the MCP pane warns that the background service can’t start, click Repair Background Service: macOS was refusing to launch it from the copy of the app it was registered from, which happens after a rebuild or after moving the app. Each client row now shows its own Repair result, and clients that aren’t installed have Install….

The MCP pane says “Address already in use”. Another process still holds the MCP port — usually a FrontierStack that crashed or hung (an earlier build, or a wedged background service) and never released it. FrontierStack retries for a few seconds first; if the port stays taken, click Free Port… next to Restart. It finds the process and checks whether it still answers. A FrontierStack copy that no longer answers is named in a confirmation, then stopped, and MCP restarts on the freed port. A copy that still answers, or a program that isn’t FrontierStack, is never stopped: the pane names it so you can quit it yourself or choose another port.

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.6Mail troubleshooting: a client can't send

Mail failures stack: a certificate problem hides a TLS problem, which hides a login problem, which hides a sender problem. Work through them in order, and read the evidence the client already has before probing the server.

Start with the client's own transcript. In Apple Mail choose Window › Connection Doctor › Show Detail. With connection logging on, Mail also keeps every transcript in ~/Library/Containers/com.apple.mail/Data/Library/Logs/Mail/, one file per server and account, so a send that failed an hour ago can still be read. The line that matters is the reply after RCPT TO.

FrontierStack covers the server side for you. The read-only Scripts preset Mail: why modern clients can't send (legacy Server.app) checks every server-side fault in fix order, a server's Mail Server Policy section audits the whole SMTP policy, and the AI Administrator can read the server's login failures and make the fixes above — each change on an approval card.

18.7Blocking mail password-guessing

Any mail server on the internet is probed around the clock by bots guessing passwords over IMAP, POP and SMTP. The answer is the one fail2ban made famous: watch the failed logins and ban the addresses that keep failing. What matters is getting the thresholds right, and never banning your own people.

Measure before you ban. Ask the AI Administrator to read the server's failed logins. On an old Apple Server.app host they are in /Library/Logs/Mail/mail-err.log; it covers all three protocols, because Postfix checks passwords through Dovecot. Expect a slow spray: a hundred or more addresses, each trying only every five to thirty minutes. Fail2ban's usual rule of 5 failures in 10 minutes catches almost none of them, so count over 24 hours.

For the preset, target the mail server and turn on Run as root. It starts as a dry run: it lists every address it would ban and changes nothing. Read that list, change MODE to install, and run it again. Bans live in a pf anchor, so /etc/pf.conf is never edited, and a background job re-checks every minute, so a reboot doesn't undo them. It uses the system Python and needs no Homebrew.

Some addresses are never banned: private ones (office network, VPN, Tailscale), anything in /var/db/mailguard/ignore, and any address that logged in successfully in the last 14 days, so a user who mistypes a password from home is safe.

Check it on the wire. After ten minutes, banned addresses should produce no new failures; the only failures left should be from addresses it hasn't seen yet. Day to day, sudo /usr/local/mailguard/mailguard.py status lists the bans, unban lifts one, and /var/log/mailguard.log records each decision. A banned address is blocked on every port, including incoming mail, because bots log in on port 25 too, and every ban expires. The AI Administrator's Mail Password-Guessing Block skill walks through all of this.

18.8A site works everywhere but here

When DNS answers but a site won't load, the cause can belong to you, your ISP, a network in between, or the site's own host. Guessing wastes an afternoon; comparing answers from different places settles it in a minute. That is what the Connection Probe in Tools does (or ask the AI Administrator why a site won't load).

The verdict names where the connection dies, why, and what to do next, with the network's NOC or abuse address when it's the destination's doing. Every device behind your router shares one public address, so a block often follows something one device did: failed logins, heavy crawling, or a monitor polling too hard.

18.9Getting 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.