Local Shell

Local Shell gives you a shell on the Mac you are sitting at, in the same window as your remote sessions — same themes, same fonts, same snippets, same tabs. It needs a small companion app, SwiftServer Helper, which you install once from SwiftServer's settings.

Why a companion app

SwiftServer ships through the App Store, so it runs inside Apple's sandbox. A shell started by the app itself would inherit that sandbox: it could not read your real home folder, could not run Homebrew tools, and would behave nothing like Terminal.app.

SwiftServer Helper solves that. It is a separate, notarized app that runs outside the sandbox as a launchd agent. The helper owns the pseudo-terminal and starts your login shell; SwiftServer connects to it over XPC and draws the result. This is the same shape other sandboxed Mac apps use for work the sandbox forbids.

Nothing else in SwiftServer depends on the helper. Without it, SSH and Mosh sessions work exactly as before.

Requirements

• macOS 15 or later.
• SwiftServer 2.2 or later for Mac.
• Mac only. Local Shell does not appear on iPhone or iPad.

Install

SwiftServer Helper is a separate download. The App Store sandbox does not let SwiftServer run or open anything it downloaded itself, so the download goes through your browser — and it is an ordinary installer package.

1. Open Settings → Local Shell and choose Download Installer. Your browser downloads SwiftServerHelper-<version>.pkg into your Downloads folder.
2. Open the downloaded package and follow the installer. It installs into your own home folder, so it never asks for an administrator password. The helper has no window and no menu bar item.
3. Go back to SwiftServer. The Local Shell page updates itself when the installation finishes; if you left it waiting, Check Again re-reads straight away. Approve the helper if macOS asks (see below).

Every published version is listed under /downloads/helper/; the current installer is SwiftServerHelper-1.1.0.pkg.

Open a local terminal

• Terminal → New Local Terminal in the menu bar, or the shortcut shown next to it in that menu.
• New Local Terminal in the Dashboard toolbar.

A local session behaves like any other terminal in SwiftServer. Closing it hangs up the shell, the way closing a Terminal.app window does.

What the shell gets

• Your login shell, read from your macOS account record — zsh unless you changed it.
• A login shell environment, exactly like Terminal.app. PATH starts at /usr/bin:/bin:/usr/sbin:/sbin and your shell rebuilds it from /etc/zprofile and your own profile, so Homebrew, asdf, nvm, and whatever else you set up are on the PATH.
• TERM=xterm-256color, COLORTERM=truecolor, and TERM_PROGRAM=SwiftServer, plus LANG derived from your locale.
• Your ssh-agent, when macOS provides its socket to the helper's login session: SSH_AUTH_SOCK is passed through, so agent keys work in a local terminal.
• Your home folder as the working directory, unless the action you used opens the session somewhere else.
• The same themes and fonts, snippets, and inspector as SSH sessions.

Because the shell runs outside the sandbox, macOS asks for file access the first time a command touches Desktop, Documents, Downloads, or a removable or network volume — exactly as Terminal.app does on a fresh Mac. The prompt names SwiftServer Helper, since that is the process running your command. Approve it once per category, or decline and work elsewhere on disk. To stop the prompts altogether, grant SwiftServer Helper Full Disk Access; the Local Shell page has a button that opens the right settings pane.

Updates

Helper updates are independent of the App Store app.

• Check for Updates in Settings → Local Shell compares the installed version against the published release. When a newer helper exists, the page offers Update Helper, and the helper replaces itself in place — no browser and no installer. A progress bar on the page follows it.
• Automatically check for updates runs the same check at most once a day when you open Settings or the main window, and shows the result on the Local Shell page. It never interrupts you with a notification.
• Close every local terminal before updating. The update replaces the running helper, so open local sessions would be hung up mid-command. Remote sessions are unaffected.

Uninstall

Use Uninstall Helper in Settings → Local Shell, or run the installed copy directly:

"$HOME/Library/Application Support/SwiftServer Helper/SwiftServer Helper.app/Contents/MacOS/SwiftServer Helper" --uninstall

Uninstalling from Settings is the normal route; the command is there for a scripted setup. Either way removes the launch agent registration, the status files the helper wrote for SwiftServer, and ~/Library/Application Support/SwiftServer Helper/. Your SwiftServer settings, machines, themes, fonts, and snippets are untouched, and remote sessions keep working. Reinstall any time from Settings → Local Shell.

Security and privacy

• The helper accepts connections only from SwiftServer builds signed by GitSwift (Team ID 7732437C8W), and SwiftServer talks only to a helper signed by the same team with the com.gitswift.SwiftServerHelper bundle identifier. Another app cannot use it to run commands.
• No network listener. The helper never opens a port and never accepts a remote connection. It reaches the network only to download its own update from swiftserver.app, when you ask it to; SwiftServer itself fetches the update manifest from the same place. The address is pinned in the helper's code, so a tampered manifest cannot redirect it.
• No entitlements. It runs as you, in your login session, with exactly your privileges.
• Distributed with a Developer ID certificate, the hardened runtime, and Apple notarization.
• Your keystrokes and shell output stay on the Mac, passed between SwiftServer and the helper over XPC.

Troubleshooting

The Local Shell page names the situation it found and gives you the one action that fixes it, so start there.

"Not Starting". The helper is on disk, but macOS is not starting it. From outside, three causes look the same: macOS is still waiting for you to allow the login item, you switched SwiftServer Helper off in Login Items, or the registration the installer ran did not take. The page offers the fix for each: Open Login Items Settings to allow or turn it on, Repair Registration to register it with macOS again, then Check Again. SwiftServer picks up the change without a restart.

"Not Responding". The helper is installed and registered but is not answering. Repair Registration registers it with macOS again, which is usually all it needs. Close your local terminals first.

"Not Installed" after it was working. The helper was deleted outside SwiftServer. Choose Download Installer to set it up again.

"Update Required". The installed helper is older than this version of SwiftServer needs. Choose Update Helper, or Download Installer if the page says the helper is too old to update itself.

"Waiting for the Installer" for a long time. SwiftServer is watching for the helper to appear. If you have not opened the downloaded package yet, open it now; if you already did, choose Check Again.

"SwiftServer Is Out of Date". Each helper release states the minimum app version it supports. Update SwiftServer from the App Store rather than reinstalling the helper.

The shell exits immediately. The helper starts the login shell recorded for your account. If that path is missing or not executable, the session ends at once. Check it with:

dscl . -read /Users/$USER UserShell

Fix it in System Settings → Users & Groups (right-click your account, then Advanced Options), or with chsh -s /bin/zsh.

Read the helper's log. The helper logs to the unified log under the com.gitswift.SwiftServerHelper subsystem, in the installer, service, and shell categories:

log stream --predicate 'subsystem == "com.gitswift.SwiftServerHelper"'
log show --last 1h --predicate 'subsystem == "com.gitswift.SwiftServerHelper"'

Use log stream while reproducing a problem, and log show for something that already happened. Include the output if you write to support.

Command-line options

The installed helper is at ~/Library/Application Support/SwiftServer Helper/SwiftServer Helper.app, and its executable accepts a few arguments. You never need these for normal use; they are here for scripted setup and for diagnosing an install.