Port psyTerm to macOS and package a native app bundle

This commit is contained in:
James Magahern
2026-11-17 11:49:40 -08:00
parent 6b2bd8c064
commit 20ca5447ef
11 changed files with 844 additions and 509 deletions
+60 -23
View File
@@ -1,6 +1,6 @@
# psyTerm
A Wayland terminal and multiplexer built with [GPUI 0.2.2](https://gpui.rs/)
A terminal and multiplexer for macOS and Linux (Wayland), built with [GPUI 0.2.2](https://gpui.rs/)
and [alacritty_terminal 0.26.0](https://docs.rs/alacritty_terminal/0.26.0/).
A separate server owns terminal emulation, shells, tabs, panes, and scrollback.
GUI processes display its snapshots and send input commands. Closing a window
@@ -8,8 +8,41 @@ detaches it; the shells keep running for the next local or remote connection.
## Build and run
Use recent stable Rust (development uses 1.96) and Linux 5.3 or newer. GUI
processes require a running Wayland desktop and a working Vulkan driver.
Use recent stable Rust and build with `--locked` to use the dependency versions
in `Cargo.lock`.
### macOS
Install Xcode or its Command Line Tools (`xcode-select --install`). GPUI embeds
its Metal shader source and compiles it when the GUI opens. To launch from a
checkout, run `cargo run --locked`.
Install cargo-bundle once to build the Finder-launchable app. This is the
version used by [Zed](https://github.com/zed-industries/zed/blob/main/script/bundle-mac).
```sh
cargo install --locked --git https://github.com/zed-industries/cargo-bundle \
--rev 2be2669972dff3ddd4daf89a2cb29d2d06cad7c7 cargo-bundle
```
Build the release executable, package it, and sign the bundle locally.
```sh
cargo build --locked --release
CARGO_BUNDLE_SKIP_BUILD=true cargo bundle --release --format osx --select-workspace-root
codesign --force --sign - target/release/bundle/osx/psyTerm.app
open target/release/bundle/osx/psyTerm.app
```
You can copy `psyTerm.app` to Applications. The bundle and CLI both open a GUI
in the launching process and connect to the same local server. Use `open -n`
with the app path for another window. The bundle's
`Contents/MacOS/psyterm` executable also accepts the CLI commands below.
### Linux
Use Linux 5.3 or newer. GUI processes require a running Wayland desktop and
a working Vulkan driver.
The server and SSH bridge do not initialize GPUI, Wayland, or Vulkan, although
the shared executable still needs its dynamically linked libraries installed.
@@ -44,13 +77,18 @@ cargo build --locked --release
The default command starts or reuses a local server, asks its zygote to fork a
GUI, and returns. Running it again opens another view of the same workspace.
The first attachment to an empty server creates a shell. Shells use the
server's `$SHELL` (falling back to `/bin/sh`), environment, and startup directory;
they receive `TERM=xterm-256color` and `COLORTERM=truecolor`.
The server retains its startup environment. Set shell or GUI environment
preferences before starting that server, or use `--gui` to launch a diagnostic
GUI directly from the current environment. After rebuilding, the server refreshes
### Shells and sessions
The first attachment to an empty server creates a shell in the server's startup
directory. Shells inherit the server's environment and receive
`TERM=xterm-256color` and `COLORTERM=truecolor`. The server uses `$SHELL`
when set. On macOS it starts a login shell and falls back to the shell in
your account settings. On Linux the fallback is `/bin/sh`.
The server retains its startup environment. Set shell preferences before
starting the server. On Linux, use `--gui` to launch a diagnostic GUI directly
from the current environment. After rebuilding on Linux, the server refreshes
its zygote for new GUI windows, preserving existing windows and shells. Changes
to server logic or the protocol still require restarting the server;
`--shutdown` also ends its shell sessions.
@@ -64,9 +102,9 @@ Finish any running work first, since shutdown ends its sessions, then launch
| Command | Behavior |
| --- | --- |
| `psyterm` | Open a local window through the server's zygote |
| `psyterm` | Open a local window attached to the server |
| `psyterm --remote user@host` | Open a local GUI connected to the remote server over SSH |
| `psyterm --gui` | Launch a GUI directly, bypassing the zygote |
| `psyterm --gui` | Run the GUI in the current process |
| `psyterm --list` | Inspect tabs and panes in the running local server |
| `psyterm --shutdown` | Stop the local server and end its sessions |
| `psyterm --server` | Run the terminal server in the foreground |
@@ -75,16 +113,17 @@ Finish any running work first, since shutdown ends its sessions, then launch
By default the socket is `$XDG_RUNTIME_DIR/psyterm/server.sock`, with a private
per-user temporary directory as fallback. A custom socket must have a real,
user-owned parent directory with mode `0700`:
user-owned parent directory with mode `0700`.
```sh
mkdir -m 700 "$XDG_RUNTIME_DIR/psyterm-dev"
cargo run --locked -- --socket "$XDG_RUNTIME_DIR/psyterm-dev/server.sock"
socket_dir=$(mktemp -d /tmp/psyterm.XXXXXXXX)
cargo run --locked -- --socket "$socket_dir/server.sock"
```
Sockets and log files are private to the current UID; peers are checked with
Linux credentials. Server and zygote logs are beside the socket as
`server.sock.log` and `server.sock.zygote.log`.
Sockets and log files are private to the current UID. psyTerm checks the peer's
UID using `getpeereid` on macOS and `SO_PEERCRED` on Linux. The server logs
to `server.sock.log` beside the socket. The Linux zygote logs to
`server.sock.zygote.log`.
SSH uses `BatchMode=yes`: configure key/agent authentication and known-host trust
before connecting. The remote host needs a compatible `psyterm` executable in
@@ -210,7 +249,7 @@ scrollback by default.
| --- | --- |
| `server.rs`, `session.rs` | Authoritative workspace, PTYs, child processes, parser, terminal grids, selection, scrolling, and resize |
| `protocol.rs`, `client.rs` | Versioned bounded messages, local socket / SSH transport, snapshot delivery |
| `launcher.rs` | Server startup, private paths, lifecycle locks, and the server-owned GUI zygote |
| `launcher.rs` | Server startup, private paths, lifecycle locks, and platform-specific GUI launch |
| `terminal.rs` | Snapshot-only GUI workspace and panes, command dispatch, focus, and animation scheduling |
| `commands.rs`, `bindings.rs`, `palette.rs` | Extensible command metadata, optional shortcuts, searchable nested menus |
| `pane_name.rs`, `label.rs` | Pane name editor, Unicode composition, and middle-truncated labels |
@@ -218,7 +257,7 @@ scrollback by default.
| `chrome.rs`, `colors.rs`, `fonts.rs` | Window chrome, terminal colors, font selection |
| `input.rs`, `main.rs` | Key/paste encoding and CLI/process-role dispatch |
The server starts the zygote on demand and manages its lifetime. The zygote
On Linux, the server starts the zygote on demand and manages its lifetime. The zygote
checks that it is single-threaded and forks GUI children **before** GPUI,
Wayland, Vulkan, font discovery, or executors initialize. Children inherit the
loaded executable mappings and avoid another `exec`; graphics and font setup
@@ -289,10 +328,8 @@ executable refreshed its zygote while the original GUI and shell stayed alive.
New live checks cover palette search/submenus and input isolation, Zellij
navigation bindings, stack insertion in both directions, collapsed-pane focus,
exit cleanup, and stack reattachment. A second client's focus changes preserve
palette input. These are Linux checks; remote-network latency and macOS remain
unverified.
palette input. These checks cover Linux Wayland.
Linux Wayland is the implemented platform; macOS is a future target. Current
limits include no arbitrary split trees or floating panes, shared per-server
Current limits include no arbitrary split trees or floating panes, shared per-server
viewport state, no disk-restored sessions, no configuration files, no application mouse reporting,
no Kitty keyboard protocol, no OSC 52 clipboard access, and no clickable links.