Ubuntu remote gxserver

Ghostex can install gxserver-rs onto an Ubuntu machine over SSH from the macOS app. The app ships a self-contained Linux package, uploads the matching architecture, starts gxserver on the remote host, then connects through an SSH tunnel.

Ubuntugxserver-rszmxSSH

End-user flow

Open Settings → Remote in the macOS app.
Add the Ubuntu machine with its SSH host, user, optional port, and either an identity file or saved Keychain password.
Click Install / Connect gxserver.
Ghostex SSHs into the machine and probes uname -s, uname -m, and /etc/os-release.
If gxserver is missing, Ghostex shows an approval modal. Click Install gxserver.
Ghostex uploads the bundled Linux package, installs it under ~/.ghostex/gxserver, starts gxserver, saves the auth token in Keychain, opens an SSH tunnel, and subscribes to remote presentation events.

What the app uploads

The upload is not a Homebrew install and does not compile on the remote box. It is a prebuilt package from the same Ghostex source tree with Linux binaries for the remote CPU architecture.

Option	What it does
`bin/gxserver`	The gxserver-rs control plane that serves the same API as macOS.
`bin/zmx`	The Linux zmx provider used for durable terminal sessions on Ubuntu.
`bin/zehn`	The prompt-history/search helper used by Ghostex session tools.
`bin/bd`	The bundled Beads CLI for project board workflows.
`code-server/lib/node`	Pinned Linux Node runtime used by the Ghostex CLI wrapper.
`portless`	The bundled Portless package used by gxserver features.
`CLI/ghostex-cli.mjs`	The shared Ghostex CLI exposed as ghostex and gx.

Remote install layout

Ghostex keeps each uploaded package as an immutable release, then points a stable symlink at the newest release. That lets reinstall replace the active package without relying on system package managers.

~/.ghostex/gxserver/releases/release-<id>/
~/.ghostex/gxserver/package -> ~/.ghostex/gxserver/releases/release-<id>
~/.ghostex/gxserver/auth/token
~/.ghostex/gxserver/state.db
~/.local/bin/gxserver -> ~/.ghostex/gxserver/package/bin/gxserver
~/.local/bin/zmx -> ~/.ghostex/gxserver/package/bin/zmx
~/.local/bin/zehn -> ~/.ghostex/gxserver/package/bin/zehn
~/.local/bin/bd -> ~/.ghostex/gxserver/package/bin/bd
~/.local/bin/ghostex -> ~/.ghostex/gxserver/package/bin/ghostex
~/.local/bin/gx -> ~/.ghostex/gxserver/package/bin/gx

Build and bundle flow

Build the Linux packages once on Ubuntu or Linux CI, one package per architecture you plan to support. The macOS app build stages those prebuilt package directories into app resources instead of rebuilding Linux tools during the macOS build.

# x64 Ubuntu package
node gxserver-rs/package-remote-linux.mjs --arch x64

# arm64 Ubuntu package
node gxserver-rs/package-remote-linux.mjs --arch arm64

# Default outputs consumed by the macOS app build
build/remote-gxserver-linux/x64/package
build/remote-gxserver-linux/arm64/package

During macOS packaging, Ghostex copies those outputs into Web/gxserver-linux-x64 and Web/gxserver-linux-arm64. A release build can require them with GHOSTEX_REQUIRE_REMOTE_GXSERVER_LINUX_PACKAGES=1.

Connection behavior after install

gxserver listens on the remote loopback API port and uses the same auth token, storage, runtime metadata, and protocol shape as macOS.
The macOS app opens a local SSH tunnel to the remote 127.0.0.1:58744 and talks to gxserver through that tunnel.
The sidebar shows remote projects, sessions, and activity states from gxserver presentation events.
Clicking a remote session opens a local Ghostty pane that SSH-attaches with ghostex attach --session-id <id> --project-id <id>.
New Ubuntu terminal sessions use the bundled Linux zmx binary, so session persistence is available on the remote machine.

Remote requirements

Ubuntu x64 or arm64 reachable from the Mac over SSH.
SSH user can write to ~/.ghostex/gxserver and ~/.local/bin.
Remote shell has standard POSIX tools: sh, uname, mkdir, tar, ln, chmod, and rm.
No system-wide sudo, apt, Homebrew, or remote source checkout is required.
The macOS app bundle must include the matching gxserver-linux-x64 or gxserver-linux-arm64 resource.

Troubleshooting

Option	What it does
`SSH failed`	Check host, user, port, identity file, ssh-agent, or the saved Keychain password.
`No compatible gxserver package`	The app bundle does not include the Linux package for the remote OS and CPU. Rebuild or install a Ghostex app bundle that includes it.
`Install failed`	Check that the SSH user can write to ~/.ghostex/gxserver and ~/.local/bin, then retry Install / Connect gxserver.
`Token unavailable`	gxserver started incorrectly or the auth token could not be read. Reinstall gxserver from Settings → Remote.
`Tunnel failed`	SSH connected, but the tunneled gxserver health check failed. Verify gxserver is running on the remote box with gxserver status --json.

Related docs