Skip to content

[Bug]: SSH remote connection fails on Windows hosts - app-server requires a Unix-like remote host #611

Open

Description

@Henry-yuan

Product or interface

Desktop app

Version

  • Desktop app (client): 3.1.16 (macOS)
  • Remote CLI @minimax-ai/code: 0.7.7 (Windows x64, installed manually via install.ps1)
  • Remote CLI installed via the official Windows installer is reported as 0.7.7

Platform

Multiple platforms

OS version and architecture

  • Remote host: Windows 11, Microsoft Windows NT 10.0.26100.0, x64
  • Client: macOS 15.7.7, arm64

Issue area

Startup / install / update

Steps to reproduce

  1. Install MiniMax Code Desktop on a macOS machine.
  2. Open Settings → Connections → SSH → Add, and pick a host entry that points at a Windows machine over SSH (host 192.168.5.x, port 22, identity file ~/.ssh/<key>). The host entry is read from ~/.ssh/config.
  3. The connection is saved and enabled, but the host stays in a failed state with: "Remote MCode installation failed. Please check the developer machine network and retry."
  4. Click Install MCode on that host entry. The remote installer fails again, and the remote machine gets a new log file under ~/.minimax-code-install-logs/install-*.log.
  5. Install the CLI on the Windows host manually instead:
    irm https://filecdn.minimax.chat/public/install.ps1 | iex
    This succeeds and mcode --version reports 0.7.7.
  6. With the CLI present, the Desktop app still cannot connect. The app-server it needs on the remote host refuses to start on Windows (see the error summary below).

Expected and actual behavior

Expected: A Windows machine reachable over SSH can be registered as an SSH remote host in Settings → Connections → SSH, and the Desktop app can drive the MiniMax Code runtime installed there — the same way a Linux host works today.

Actual: Two independent Windows-specific failures block this:

  1. The Desktop remote installer runs the Unix installer on Windows. It executes install.sh on the Windows host, and that script rejects the platform:

    ==> [1/5] Checking platform and install location
    error: Windows is not supported by install.sh; run the install.ps1 command in PowerShell.
    

    The official install.ps1 works correctly when run manually in PowerShell on the same host.

  2. The remote app-server refuses to start on a Windows host. Even after the CLI is installed correctly, the app-server the Desktop app needs to connect to is rejected:

    mcode app-server daemon bootstrap --auth-mode remote-oauth
    {"action":"bootstrap","error":{"code":"appServerDaemonCommandFailed",
     "message":"The app-server daemon requires a Unix-like remote host.",
     "recommendedAction":"inspectRemoteLogs"}}
    
    mcode app-server --listen unix://<path> --foreground
    The app-server Unix transport requires a Unix-like remote host.
    

    Both the daemon path and the direct --listen unix:// path are refused, so this is not a configuration problem — the Windows host cannot host the app-server at all.

Redacted error summary

# Desktop side (macOS client), Settings -> Connections -> SSH
[info] [SshRuntime] connection failed: The remote CLI path could not be discovered.
[info] [SshRecovery] {"hostId":"<windows-host>","state":"action_required","phase":"stopped",
                       "code":"remote_mcode_not_found","disposition":"action_required"}
# Windows remote host, Desktop "Install MCode" action
[mcode-install] operationId=manual-<id> stage=1
==> [1/5] Checking platform and install location
error: Windows is not supported by install.sh; run the install.ps1 command in PowerShell.
[mcode-install] operationId=manual-<id> stage=1 exitCode=1
# Windows remote host, manual CLI install -> succeeds
> irm https://filecdn.minimax.chat/public/install.ps1 | iex
... Installation complete: @minimax-ai/code@0.7.7 (fresh)
> mcode --version
0.7.7
# Windows remote host, app-server bootstrap (the blocker)
> mcode app-server daemon bootstrap --auth-mode remote-oauth
{"action":"bootstrap","error":{"code":"appServerDaemonCommandFailed",
 "message":"The app-server daemon requires a Unix-like remote host.",
 "recommendedAction":"inspectRemoteLogs"}}

> mcode app-server --listen unix://<path> --foreground
The app-server Unix transport requires a Unix-like remote host.

Screenshots

The Settings → Connections → SSH editor for the Windows host is filled in correctly (host 192.168.5.x, port 22, identity file ~/.ssh/<key>), and the host entry shows the "Remote MCode installation failed" state. Screenshot can be provided on request.

Additional notes

Before submitting

  • I have searched existing issues.
  • I have included my version and removed sensitive information.

Question for the maintainers

Is Windows supported (or planned) as an SSH remote host for the Desktop app? If it is not, could the Desktop app either:

  1. detect a Windows remote host and run install.ps1 instead of install.sh, and
  2. surface a clear "Windows remotes are not supported yet" message instead of the current generic installation failure?

Documenting the current limitation in the Connections settings page would also help — currently the SSH remote feature has no documentation page, and the only platform guidance I could find is in the changelog.

Thanks for taking a look.

Activity

  1. Ralle1976 commented on Nov 20, 2026

    @Ralle1976
    Contributor

    Reachability balance first (the label is desktop, so this comes before the measurements)

    I looked for both halves of your report in this repository's published source and found neither one there. That is why I am commenting here with measurements rather than a patch.

    1. The Desktop half is out of scope by the repository's own publication rule.
    docs/publication-authorization.md:15 — "The published source does not include the Desktop application's source, internal Git history, private review material, account data, logs, sessions, credentials, or later unreviewed additions." docs/tui-capabilities.md:212 repeats it for the runtime side — "Desktop HTTP services and internal generated IDL remain outside the public repository." So Settings → Connections → SSH, the ~/.ssh/config host entries, the "Install MCode" button and the install.sh-vs-install.ps1 choice cannot be fixed from this tree — that is your SshRuntime / SshRecovery log side.

    2. The CLI half is also not in the published source, although it is in the shipped npm package.
    This is the part worth stating precisely, because it is easy to assume the opposite.

    probe result in the published tree at 3c21163
    git grep -c -i "app-server" 1 hit, and it is a comment: packages/local-runtime/src/api/host-route-contexts.ts:175
    git grep -n "Unix transport", git grep -n "unsupported_platform" 0 hits
    git log --all -S "requires a Unix-like remote host" empty — the string has never existed in this repository's history
    CLI command registry packages/tui/src/cli/program.ts:95-359 init, exec, acp, login, logout, update, telemetry, status, preview, provider, plugin, … — no app-server command
    public export map (derived via scripts/lib/package-exports.mjs:18-45 from release/extraction.json → packageRoots) 132 exported specifiers, 0 of them matching app-server / ssh / daemon / remote
    build entry point scripts/build.mjs:80-81 cli: "packages/tui/src/index.ts" — the published CLI is built from packages/tui only

    The npm package you installed does contain the command (mcode app-server --help → "Run the MCode SSH app-server"). The source of that command is simply not part of this repository's public projection, so no PR against this repo can move the Windows gate you hit. docs/open-source-status.md:3 scopes the tree to "the terminal TUI, headless CLI, ACP implementation, and the public distribution tooling around them" — the app-server is none of those.

    So the honest answer to "is this an OSS-repo bug?" is: no, not one that this repository can fix. What this repository can contribute is the measurement below, because the gate you hit is a transport choice, not a broken Windows runtime — and that is the one dimension your report does not contain.


    Contribution: the Windows refusal is bound to the transport, not to the app-server

    Your two quoted failures are real and I reproduced both byte-for-byte on a Windows host. But they are two different gates, and neither of them is the app-server itself.

    Versionsanker

    CLI mcode --version → 0.7.8 (global npm install)
    npm latest npm view @minimax-ai/code version → 0.7.8 (latest), installed == published
    Source read main = 3c21163 (release/extraction.json → sourceRevision baseline 9b9885e; root package.json version 0.7.2)
    Toolchain Node v24.18.0
    Platform Microsoft Windows 11 Pro, 10.0.26200, x64
    Isolation all measurements under a fresh %TEMP% lab with --data-dir pointed at it; ~/.minimax was not modified
    SSH client OpenSSH 10.3p1 present (ssh.exe, client only — no sshd on this host, so no end-to-end SSH handshake was possible)

    Repro command (Windows, isolated, one block)

    $lab = Join-Path $env:TEMP 'w16-611'; New-Item -ItemType Directory $lab -Force | Out-Null
    $env:MCODEX = 'mcode'
    & $env:MCODEX app-server --listen "unix://$lab/x.sock" --foreground --data-dir $lab
    & $env:MCODEX app-server daemon bootstrap --data-dir $lab
    & $env:MCODEX app-server --listen 'stdio://' --foreground --data-dir $lab

    Measured matrix on Windows (CLI 0.7.8):

    invocation result
    app-server --listen unix://<path> --foreground The app-server Unix transport requires a Unix-like remote host.
    app-server daemon bootstrap {"action":"bootstrap","error":{"code":"appServerDaemonCommandFailed","message":"The app-server daemon requires a Unix-like remote host.","recommendedAction":"inspectRemoteLogs"}}, exit 1
    app-server daemon start same message, exit 1
    app-server daemon status works — returns daemon state
    app-server daemon version works — returns state incl. "version":"0.7.8"
    app-server proxy not platform-gated; fails with connect ENOENT <data-dir>\app-server-control\app-server.sock because no server can be listening there
    app-server --listen stdio:// --foreground starts and serves JSON-RPC
    app-server --stdio --foreground starts (same path)

    The first two rows are identical to your quoted output, so the reproduction is confirmed; the interesting part is the last two.

    The stdio:// transport completes the full app-server handshake on Windows. I sent a real initialize request over stdio and got a real result back (no error, process stayed alive):

    {"id":1,"result":{"protocolVersion":1,
      "serverInfo":{"name":"mcode-app-server","title":"MCode SSH App Server","version":"0.7.8"},
      "environment":{"platformFamily":"windows","platformOs":"win32","arch":"x64","userName":"<redacted>","homeDir":"<redacted>","dataDir":"<redacted>"},
      "hostIdentity":{"authMode":"remote-oauth","protocolVersion":1,"version":"0.7.8","region":"en","buildEnv":"prod"},
      "capabilities":{"methods":["account/read","account/login/start","account/login/cancel","account/logout","server/prepareRestart","desktopService/transport"],
        "transports":["stdio","unix-websocket"],
        "desktopService":{"contract":"DesktopService","transportMethod":"desktopService/transport","transportProtocolVersion":2,"binaryPayloadEncoding":"base64",...},
        "features":["project.icon.update","computer.use"],
        "reconnect":{"history":true},
        "auth":{"deviceAuthorization":true,"credentialTransfer":false,"mode":"remote-oauth"}}}}

    Three things in that payload are directly relevant to your question:

    • environment.platformFamily: "windows" / platformOs: "win32" — the runtime is Windows-aware; it reports its own platform instead of refusing to start.
    • capabilities.transports: ["stdio","unix-websocket"] — the server advertises unix-websocket on this very win32 host, while the same binary refuses --listen unix:// there. The advertisement and the gate disagree.
    • capabilities.features contains computer.use — the exact feature the CLI changelog attributes to a Windows remote (see below).

    So the Windows-specific mechanism is a transport/daemon gate, and it is narrower than "the app-server does not run on Windows". Read from the published bundle (node_modules/@minimax-ai/code/chunks/run-app-server-command-EWT4AIHT.js, minified, single-line chunk — hence function names instead of source lines):

    function in the bundle behaviour
    Ci(listenUri) "stdio" / "stdio://" → {kind:"stdio"}; "unix://…" → {kind:"unix",socketPath}; anything else → Unsupported app-server listen URI: … Use stdio:// or unix:///path.
    Ri(...) (server bootstrap) if (s.kind === "unix" && platform === "win32") throw new Error("The app-server Unix transport requires a Unix-like remote host.") — the refusal is conditioned on the transport kind
    daemon start() if ((options.platform ?? process.platform) === "win32") throw new C("unsupported_platform", "The app-server daemon requires a Unix-like remote host.") — unconditional for the daemon
    daemon install/prepare dn(...) if (platform === "win32") throw new Error("The app-server daemon requires a Unix-like remote host.")
    control-directory check n = process.getuid?.() → n === undefined on Windows → App-server control directory must be a real directory owned by the current user: …; and (mode & 0o777) !== 0o700 → App-server control directory requires effective 0700 permissions; use a private directory on a filesystem supporting Unix permissions: …
    proxy mode runProxy({ socketPath, input: stdin, output: stdout }) — connects to a Unix socket path

    Why the Unix transport cannot simply be enabled on Windows — measured, not assumed (Node v24.18.0, this host):

    probe result
    net.createServer().listen("<fs path>") — 4 path variants (relative, drive-letter, backslash, short %TEMP% path) EACCES: permission denied on every variant
    net.createServer().listen("\\\\.\\pipe\\<name>") works (Windows named pipe)
    process.getuid on Windows undefined
    directory permission bits on Windows 0o666, not 0o700

    So the Windows-native IPC primitive for this design is a named pipe, not a Unix socket — and the daemon's control-directory ownership/permission preconditions are Unix-shaped by construction, independent of the socket itself. That is a design consequence, not a small portability bug, and I am not proposing a change to it.

    A documentation inconsistency worth closing on your side of the report. (Note that these entries live in the CHANGELOG.md of the published npm package; the published source tree at 3c21163 contains no markdown that mentions the app-server at all.) The shipped CLI changelog already describes Windows as a valid app-server host:

    • CHANGELOG.md of the published package (v0.7.8, node_modules/@minimax-ai/code/CHANGELOG.md:82), entry 0.7.6 (2026-11-05): "When Desktop opens a project over SSH, mcode app-server on the remote macOS or Windows machine provides Computer Use there; permissions are granted on that machine with /computer-use permissions."
    • same CHANGELOG.md:250, entry 0.6.12 (2026-10-15): "A standalone App Server supports SSH connections to a remote Runtime, including connection recovery, authentication state, and version updates."

    and the handshake above confirms that a Windows remote can carry the computer.use feature over stdio. Meanwhile the same binary refuses the Unix transport and the daemon on win32. I cannot tell from here which of the two is the intended product boundary — that is a question for the maintainers, and it is the same question your report asks.


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    desktopMiniMax Code desktop app

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions