agent-ssh

Native macOS, iPhone, and iPad SSH workspace. AppKit + SwiftUI shell, SwiftTerm for the PTY, ssh-commander-core for the protocol layer, uniffi for the FFI bridge. Stable internal package names and URLs retain agent-ssh for compatibility.

Stack

Layer	Lives in	Notes
App shell	AgentSshApp/, AgentSshMobile/	AppKit window + SwiftUI views, SwiftTerm
Swift framework	Sources/AgentSshMacOS/	Cross-target models, stores
FFI bridge	src/	Rust → Swift via uniffi proc-macros
Generated bindings	bindings/	agent_ssh.swift, agent_sshFFI.h, module.modulemap
Protocol layer	crates.io: ssh-commander-core, ssh-commander-pg-parquet	external
Xcode project	Mc-Ssh.xcodeproj	generated from project.yml by xcodegen

Prerequisites

• Xcode 27+ (Swift 6.4, macOS 27 / iOS 27 SDKs — what CI builds with) and command-line tools (xcode-select --install)
• Rust 1.95+ (edition 2024) — rustup default stable
• just — brew install just
• xcodegen — brew install xcodegen (auto-installed by just mac-bootstrap)

just bootstrap          # one-time: xcodegen + macOS + iOS Rust targets

Build & run

# Native macOS app (ad-hoc signed, opens Finder window)
just mac-build
just mac-run

# Physical iPad / iPhone over USB or Wi-Fi (signing team from project.yml)
just run-on-ipad
just run-on-iphone

# iPad simulator (boots a sim, installs, launches)
just run-on-ipad-sim "iPad Pro"

# Full local CI pass
just ci-local

Run just (no args) for the full recipe list.

Common workflows

Edit Rust FFI surface

# 1. Edit src/ffi/ (or src/lib.rs)
# 2. Regenerate Swift bindings
just mac-bindings
# 3. Rebuild
just mac-build

The bindings under bindings/ are committed — regenerate and commit them whenever the FFI changes. Hand-patching bindings/agent_ssh.swift will appear to work but the per-function uniffi checksums will diverge from what the Rust lib reports at runtime, and rshellInit() will panic with _assertionFailure.

Edit project.yml

just mac-gen            # regenerate Mc-Ssh.xcodeproj

The xcodeproj is gitignored — mac-gen is automatic before any mac-* build via _ensure-xcodeproj.

Sign + notarize a release DMG

export APPLE_SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)"
export APPLE_ID="…"
export APPLE_TEAM_ID="…"
export APPLE_APP_SPECIFIC_PASSWORD="…"

just mac-release true   # build → DMG → notarize → staple

For a build-only DMG without notarization, drop the env vars and run just mac-release (defaults to false).

Sparkle auto-updates

just mac-sparkle-keygen            # one-time, populate Info.plist with the public key
just mac-sparkle-appcast ./dist    # generate appcast.xml from a folder of DMGs

Repo layout

.
├── Cargo.toml              # FFI crate manifest
├── build.rs                # uniffi build hook
├── uniffi-bindgen.rs       # bindgen entry point (cargo run --bin uniffi-bindgen)
├── src/                    # Rust FFI bridge (bridge.rs, ffi.rs, monitor.rs)
├── bindings/               # generated Swift bindings (committed)
├── project.yml             # XcodeGen manifest (single source of truth)
├── Mc-Ssh.xcodeproj/      # generated; gitignored
├── Package.swift           # SPM wrapper around the static lib
├── Sources/AgentSshMacOS/    # cross-target Swift framework (models + stores)
├── AgentSshApp/              # macOS app target — SwiftUI views + managers
├── AgentSshMobile/           # iPadOS / iOS app target
├── Tests/                  # XCTest harness (AgentSshMacOS + AgentSshApp + Beta smoke)
├── scripts/                # release, notarize, find-sparkle-tool helpers
├── justfile                # command surface
├── README.md               # you are here
├── AGENTS.md               # AI-agent code tour
└── TOOLS.md                # in-app feature catalog

Troubleshooting

error: There is no XCFramework found at .../Sparkle.xcframework — stale Xcode SourcePackages cache pinned to the old absolute path. Wipe and regenerate:

rm -rf build .build Mc-Ssh.xcodeproj
just mac-gen
just mac-build

Thread 3 Crashed: rshellInit() → _assertionFailure — uniffi binding checksums don't match the rebuilt Rust lib. Always regenerate via just mac-bindings after touching the FFI; never hand-edit the generated Swift.

Build is slow on first run — russh and parquet (transitive via ssh-commander-pg-parquet) compile from source. Subsequent incremental builds are fast.

Contributing

Contributions are welcome — see CONTRIBUTING.md for setup, local checks, and the FFI workflow. All contributors agree to the CLA.

License

GNU AGPL-3.0 © 2026 Andreas Mueller. The project is also available under separate commercial terms; reach out if AGPL doesn't fit your use.