Documentation

Prerequisites

• A Mac running macOS 13 (Ventura) or later
• An iPhone or iPad running iOS/iPadOS 17 or later
• Homebrew installed on your Mac (brew.sh)
• Both devices connected to the internet (they do not need to be on the same network)

Mac Setup

1. Install the CLI

Open Terminal on your Mac and run:

Already have it installed? Make sure you're on the latest version:

2. Start TermOnMac

Run the CLI to start the relay connection and display a QR code:

On first launch, the CLI will:

• Generate a unique identity key pair for your Mac
• Store it in ~/.config/termonmac/ with restricted permissions
• Connect to the relay server and display a QR code in your terminal

3. Keep it running

Leave the CLI running while you want to accept connections. You can check the status at any time:

iOS Setup

1. Download the app

Install TermOnMac from the App Store.

2. Sign in

Open the app and sign in using one of the supported providers:

• Sign in with Apple
• GitHub
• Google

Your account is used for relay authentication and subscription management. No password is stored on our servers.

Pairing Your Devices

Scan the QR code

After signing in on the iPhone app, tap the Scan QR Code button. Point your camera at the QR code displayed in your Mac terminal.

What happens during pairing

1. The QR code contains your Mac's public key and a pairing token
2. Your iPhone and Mac perform a Curve25519 ECDH key exchange to establish a shared secret
3. The shared secret is stored in the iOS Keychain (iPhone) and the local config file (Mac)
4. All future communication between the devices is encrypted with AES-256-GCM

Alternative: Photo picker

If you can't point your camera directly at the Mac screen (e.g., the Mac is remote), you can screenshot the QR code and use the photo picker option to scan it from your Photos library.

Saved connections

Once paired, your Mac appears as a saved connection on the home screen. Tap it to reconnect anytime — no re-scanning needed. You can rename connections by tapping on them.

Using the Terminal

Once connected, you get a full pseudo-terminal (PTY) session on your Mac. The terminal emulates a standard 80×24 character grid with 1,500 lines of scrollback history.

Input

• Type commands using the on-screen keyboard
• Use the shortcut toolbar above the keyboard for common keys: Tab, Ctrl, Esc, arrow keys, and more
• Your input draft is preserved per session — if you switch sessions and come back, your unfinished command is still there

Input history

Each session maintains a local input history (up to 32 KB) stored on your Mac in the .remotedev/input-log directory. This history never leaves your Mac.

Scrollback

Swipe up to scroll through terminal output. The scroll position is preserved when new output arrives, so you won't lose your place while reading logs.

Clipboard

You can paste from your iPhone clipboard into the terminal. A 10-second clipboard guard prevents accidental pastes right after copying.

Keyboard

Touch keyboard toolbar

A toolbar above the on-screen keyboard provides the keys iOS lacks:

• Tab, Ctrl, Esc, arrow keys
• Modifier toggles — tap Ctrl or Alt to latch it, then tap another key to send the combination (e.g., Ctrl + C)
• Shortcut search — type in the search field to find and trigger your custom shortcuts by name

Hardware keyboard (iPad)

Plug in a Magic Keyboard or pair any external keyboard. All shortcuts use the ⌘⌥ (Cmd+Opt) prefix to avoid conflicts with terminal and system keybindings.

Sessions

Navigation

Terminal

Build

Discovering shortcuts

• First-time tooltip when a hardware keyboard connects
• Keyboard icon in the toolbar shows the full list

Session Management

TermOnMac supports multiple concurrent terminal sessions per connection, so you can run different tasks in parallel.

Session limits

Creating & switching sessions

Tap the session tabs at the top to switch between active sessions. Tap + to create a new session. Each session is an independent PTY on your Mac.

Renaming sessions

Open the session sidebar and tap on a session name to rename it. This helps you keep track of what each session is for (e.g., "server", "build", "git").

Reordering sessions

Long-press and drag sessions in the sidebar to reorder them.

Session info

Tap the info button on a session to see details like the process ID (PID), working directory, and current git branch.

Reattaching sessions

If your connection drops and you reconnect, your existing sessions are automatically reattached — you pick up right where you left off.

Session Handoff

You can seamlessly transfer an active terminal session between your iPhone and Mac. Only one device controls a session at a time — the other is notified and can reclaim it at any moment.

iPhone to Mac

You have a session running on your iPhone and want to continue on your Mac's native terminal.

1. On your Mac, open the TUI and go to Sessions:
   $ termonmac

   Select a session and press a or Enter to attach.

2. Or attach directly from the command line:
   $ termonmac attach <session-id>

   If there's only one session, you can omit the ID — it attaches automatically.

3. The Mac terminal takes control. On your iPhone, the session shows a "Session controlled by Mac" overlay with a "Tap or type to reclaim" prompt.
4. When you're done on the Mac, detach to release it back:
   $ termonmac detach

   Or press Ctrl-] followed by d while attached. You can also press d on the session in the TUI.

5. The iPhone app is notified and can resume the session immediately. Any output that happened while the Mac was in control is replayed to the iPhone.

Mac to iPhone

You have a session running from your Mac (via termonmac attach or the TUI) and want to continue on your iPhone.

1. Open the TermOnMac app on your iPhone and connect to your Mac.
2. The session appears in the available sessions list, marked as Mac-controlled.
3. Tap the session to attach it. Start typing — your input automatically reclaims the session from the Mac.
4. The Mac terminal receives a notification that the session was taken over by iOS. The termonmac attach process exits.
5. Any output you missed while the Mac had control is replayed to your iPhone screen.

TUI session shortcuts

The TUI Sessions menu supports these keybindings:

Build System

TermOnMac includes a built-in interface for building Xcode projects remotely without typing xcodebuild commands manually.

Project detection

When you open the build view, TermOnMac scans for .xcodeproj and .xcworkspace files in your session's working directory and presents them for selection.

Build configuration

• Scheme: Select from available schemes in the project
• SDK: Choose the target SDK (e.g., iphoneos, iphonesimulator)
• Configuration: Debug or Release
• Team ID: Set your development team for code signing

Build output

Build logs stream in real time. You can scroll through the output to inspect warnings and errors as they appear.

Build pipeline

For advanced workflows, you can set up a multi-step pipeline:

1. Build — Compile the project
2. Test — Run unit/UI tests
3. Archive — Create an archive for distribution
4. Upload — Submit to App Store Connect

Configure your App Store Connect credentials in the build settings to enable the archive and upload steps.

Git Worktrees

TermOnMac has built-in support for git worktrees, allowing you to work on multiple branches simultaneously without stashing or switching.

Creating a worktree

From the session sidebar, tap Create Worktree on any session that is inside a git repository. This creates a child session with its own working directory checked out to a new branch.

Directory layout

You can choose how worktree directories are organized in the room settings:

• Grouped: All worktrees under a single parent directory
• Sibling: Worktrees as sibling directories next to the main repo
• Flat: Worktrees in a flat structure

Merging a worktree

When you're done with a worktree branch, use the Merge action in the sidebar. TermOnMac will:

1. Check for uncommitted changes (dirty state)
2. Attempt to merge the worktree branch into the parent branch
3. Optionally enforce fast-forward-only merges (configurable in room settings)

If there are merge conflicts, you'll be notified and can resolve them in the terminal.

Dirty state protection

If you try to close a worktree session that has uncommitted changes, TermOnMac will warn you before proceeding.

Custom Shortcuts

Create reusable terminal commands and scripts that you can trigger with a tap.

Creating a shortcut

Open the Shortcut Manager from the terminal view. Tap + to create a new shortcut with:

• A name and optional key combination
• The command or script to execute

Using shortcuts

Shortcuts appear in the toolbar above the keyboard. Tap to execute instantly in the current session.

Import & export

Shortcuts can be exported as JSON files for backup or sharing with teammates. Import shortcuts from a JSON file to quickly set up a new device.

Cloud backup

You can back up your shortcuts to the cloud and restore them on any device signed in with the same account.

Auto-Run on Connect

Configure a sequence of commands or shortcuts to execute automatically every time you connect to a Mac.

Setting up auto-run

1. Open the Room Settings for your saved connection
2. Enable Auto-Run
3. Add shortcuts or commands to the auto-run sequence

For example, you could set up auto-run to cd into your project directory and launch claude — so every time you connect, your AI coding assistant is ready to go.

Account & Subscription

Subscription tiers

Managing your subscription

Go to iPhone Settings > Apple ID > Subscriptions > TermOnMac to upgrade, downgrade, or cancel. You can also manage subscriptions from within the app. After cancellation, paid features remain active until the end of the billing period.

Deleting your account

Navigate to Account Settings > Delete Account in the app. Your account will be immediately deactivated. After a 30-day grace period, all data is permanently deleted. You can contact us within 30 days to cancel the deletion.

Security & Encryption

TermOnMac is designed with a zero-knowledge architecture. The relay server forwards encrypted packets but never decrypts them.

Encryption details

• Key exchange: Curve25519 ECDH during QR code pairing
• Session encryption: AES-256-GCM for all terminal data
• Transport: TLS (WSS) between devices and relay

Key storage

• iPhone: Encryption keys and room secrets are stored in the iOS Keychain
• Mac: Identity key is stored in ~/.config/termonmac/ with restricted file permissions

What the relay server can see

• Connection metadata (timestamps, IP addresses, connection duration)
• Account information (email, subscription status)

What the relay server cannot see

• Terminal input or output
• File contents
• Commands you run
• Build output or logs

Troubleshooting (Mac)

If something isn't working as expected, try these steps in order — from lightest to heaviest.

1. Restart the service (keeps sessions)

This restarts the relay connection without killing your active terminal sessions:

You can also disable and re-enable the service:

2. Full reset (drops sessions)

If a restart doesn't help, a full reset will tear down everything and start fresh. This will terminate all active sessions.

After resetting, run termonmac to start again and re-pair from your iPhone if needed.

3. Update to the latest version

Make sure you're running the latest CLI — many issues are fixed in newer releases:

Need more help?

Visit our Support page or email us at quietlight.work@gmail.com.