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 a program it downloaded itself, so the download goes through your browser; SwiftServer takes over from there.

1. Open Settings → Local Shell and choose Download and Install. Your browser downloads the current release into your Downloads folder.
2. As soon as the download finishes, SwiftServer verifies that the helper is signed by GitSwift and asks macOS to open it. If macOS asks whether to open an app downloaded from the Internet, choose Open; the helper is notarized. It copies itself to ~/Library/Application Support/SwiftServer Helper/, registers its launch agent, and reports the result in an alert. It has no window and no menu bar item.
3. Approve the helper if macOS asks (see below). The Local Shell page shows the installed version a few seconds later.

If you downloaded the helper by hand instead, every published version is listed under /downloads/helper/ (the current one is SwiftServerHelper-1.0.0.zip). Leave it in Downloads and use Install from Downloads on the Local Shell page, or simply open SwiftServer Helper yourself.

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

Updates

Helper updates are independent of the App Store app.

• Check for Updates in Settings → Local Shell compares the installed version against the published manifest. When a newer helper exists, the page offers Download and Install, which works exactly like the first install.
• 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

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. The one request Local Shell makes over the network is fetching the update manifest from swiftserver.app.
• 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

SwiftServer does not detect the helper. Check System Settings → General → Login Items & Extensions for SwiftServer Helper and turn it on. If it is missing entirely, open the downloaded SwiftServer Helper again — a partial install leaves the app on disk without a registered agent.

"Requires approval". macOS registered the agent but is waiting for you. Use Open Login Items Settings and enable the entry; SwiftServer picks up the change without a restart.

The helper is too old. SwiftServer needs a helper that speaks its protocol version. Run Check for Updates and download the offered build.

SwiftServer is too old. Each helper release states the minimum app version it supports. If Local Shell reports that, 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.