What causes "MCP gateway is only supported on Unix hosts" in astrid-runtime/astrid?

Run the gateway on Linux or macOS.

MCP gateway is only supported on Unix hosts

Error message

MCP gateway is only supported on Unix hosts

What it means

The MCP gateway itself is Unix-only (Unix domain socket transport). On non-Unix targets a stub `gateway` module is compiled whose run() always fails with this error, keeping the CLI buildable everywhere while making the limitation explicit.

Source

Thrown at crates/astrid-cli/src/commands/mcp/mod.rs:68

        _workspace: Option<&Path>,
    ) -> Result<ExitCode> {
        anyhow::bail!("MCP gateway attach is only supported on Unix hosts")
    }
}
mod elicit;
mod form_elicitation;
#[cfg(unix)]
mod gateway;
#[cfg(unix)]
mod idle;
#[cfg(not(unix))]
mod gateway {
    use std::process::ExitCode;

    use anyhow::Result;

    pub(crate) async fn run(_principal: Option<&str>) -> Result<ExitCode> {
        anyhow::bail!("MCP gateway is only supported on Unix hosts")
    }
}
mod grant;
mod ingress;
#[cfg(unix)]
mod lifecycle;
#[cfg(not(unix))]
mod lifecycle {
    use std::process::ExitCode;

    use anyhow::Result;

    pub(crate) async fn ready(_principal: Option<&str>, _format: &str) -> Result<ExitCode> {
        anyhow::bail!("MCP gateway readiness is only supported on Unix hosts")
    }

    pub(crate) async fn stop_gateway() -> Result<()> {
        Ok(())

View on GitHub (pinned to affd8760f4)

Solutions

Run the gateway on Linux or macOS.
Use WSL2 on Windows to host the gateway.
Adjust CI to a Linux runner for gateway tests.
Contribute a Windows-named-pipe transport if cross-platform gateway support is required.

Example fix

// before
# windows CI job
run: astrid mcp gateway start
// after
runs-on: ubuntu-latest
run: astrid mcp gateway start

Defensive patterns

Strategy: validation

Validate before calling

if !cfg!(unix) {
    eprintln!("MCP gateway requires Linux or macOS");
    std::process::exit(1);
}

Type guard

fn supports_mcp_gateway() -> bool { cfg!(unix) }

Try / catch

match gateway::run(principal).await {
    Err(e) if e.to_string().contains("only supported on Unix hosts") =>
        eprintln!("host the gateway on a Unix machine (or WSL2)"),
    other => other?,
}

Prevention

Deploy the gateway only to Linux/macOS hosts
Exclude gateway tasks from Windows CI
Document platform requirements for operators
Consider named-pipe transport if Windows support is needed

When it happens

Trigger: Invoking `astrid mcp gateway ...` (start/run the gateway) on Windows or any non-Unix host.

Common situations: Deploying the gateway on Windows servers; running CLI tests on a Windows dev machine; CI runners using Windows images.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/cf9667dd334e9998. Report an issue: GitHub.