Muxy

Remote Servers

Muxy can work with projects on other computers over SSH. Each computer runs its own muxy-server, so remote terminals keep running when you disconnect, just like local ones. Remote projects sit in the same sidebar as local ones, marked with their server.

flowchart LR
    APP["Desktop app or muxy"] -->|"SSH · muxy stdio"| REMOTE["muxy-server<br/>on the other computer"]

Requirements

  • SSH access to the computer with your keys, agent, or certificates. The desktop app also supports password logins.
  • A trusted host key. Run ssh <host> once to accept it.
  • Muxy installed there, on PATH or in ~/.local/bin, at a version that speaks the same protocol as yours.
  • macOS 14 or newer, or Linux with glibc 2.35 or newer, on x86_64 or ARM64.

On Linux hosts that end your processes when you log out, run loginctl enable-linger so the server keeps running after SSH disconnects.

In the desktop app

  1. Open the Remote section at the bottom of the sidebar and choose Add Server….
  2. Enter the SSH host (a host name, address, or ~/.ssh/config alias), and optionally the user, port, and identity file.
  3. Choose Test Connection. If Muxy isn't installed there, the app offers to install the same version into ~/.local/bin.
  4. Add projects with Add Project → Remote, which browses the server's folders.
  • Passwords are asked when connecting and kept only in memory until you quit.
  • A dropped server reconnects on its own, waiting longer each time. It stops retrying when it needs you, for example for a password or a new host key.
  • Forget a server to remove it and its projects from this app. Nothing on the server changes.
  • The status bar shows the current project's server, with connect, restart, and stop.

Custom SSH commands

If a VM manager or another tool handles SSH for you, turn on Custom command in Add Server… (or Edit…) and enter its command prefix, for example:

swiftvm ssh my-vm

Muxy runs that local program directly and appends its remote command as one argument. The prefix must include the target machine and any flags or -- separator your tool needs. Muxy does not add SSH flags, a host, or a port in this mode. The same prefix is used for Test Connection, installation, normal connections, and reconnects.

  • The tool must accept a remote shell command as its last argument and relay stdin/stdout unchanged without allocating a TTY. Interactive-shell-only tools are not supported. Add your tool's non-interactive/no-TTY flags if needed.
  • Authentication and host-key verification belong to the tool. Set them up in a terminal first; Muxy's password and identity-file controls do not apply here.
  • Single/double quotes and backslashes group arguments, so paths and VM names can contain spaces. Shell variables, ~, wildcards, pipelines, redirects, aliases, and command substitutions are not expanded. Use an absolute program path if the tool is not on the desktop app's PATH.
  • Only configure commands you trust: they run locally with your permissions on connection and reconnection. Do not put passwords or tokens in the command; it is saved in plain text in settings.toml.

For tools with a different argument convention, use an executable wrapper script that accepts the last argument as the remote command and forwards it without changing stdin/stdout. The remote computer still needs Muxy and the same OS requirements listed above.

A custom-command entry in settings.toml uses ssh_command instead of ssh:

[[servers]]
id = "6f9619ff-8b86-4011-b42d-00c04fc964ff" # use a unique UUID
name = "Development VM"
ssh_command = "swiftvm ssh my-vm"

From a shell

Put --host first to use another computer's server:

muxy --host devbox                 # terminal UI
muxy --host devbox project list    # any CLI command
muxy --host ssh://me@devbox:2222   # with a user and port

--host takes user@host, an ~/.ssh/config alias, or ssh://user@host:port. It never prompts, so use a key or an agent. Folder arguments must be absolute paths on that computer.

Working with remote files

  • Files dropped or pasted into a remote terminal, or sent from the composer, are uploaded and their remote path is pasted.
  • Cmd-clicking a remote file offers a read-only copy on this Mac, or its path.
  • Git runs on the server. Pull request features need gh installed and signed in there.
  • AI commit and pull request actions run on this Mac, so they only work when the project's folder also exists here.

Updating

Muxy never updates a remote computer by itself. When versions can't talk, the app shows the command to run there. To update by hand, follow the installation instructions on that computer with --replace, choosing the same channel and a compatible version.

Edit this page on GitHub