# Winx: A Rust MCP Runtime That Keeps Remote Shell Sessions Alive

> Winx is a remote-first MCP runtime written in Rust, offering durable PTY sessions over Streamable HTTP and a unified file-editing protocol. It targets teams that need authenticated, loopback-bound remote access to a development machine from cloud LLM clients.

**gabrielmaialva33/winx-code-agent** — 🦀 A high-performance code agent written in Rust, combining the best features of WCGW for maximum efficiency and semantic capabilities. 

- Repository: https://github.com/gabrielmaialva33/winx-code-agent
- Website: https://crates.io/crates/winx-code-agent
- Stars: 38 · Forks: 8
- Language: Rust
- License: MIT
- Published: 2026-08-23 · Updated: 2026-08-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/gabrielmaialva33-winx-code-agent

## What Winx Solves and Who It Is For

Winx addresses a specific pain: cloud-hosted LLM clients, like ChatGPT, need to execute commands and edit files on a developer's machine, but HTTP is stateless and a dropped connection usually kills the session. Winx is a remote-first MCP runtime that keeps a real bash process alive in a per-session guardian process, even when the HTTP client disconnects. It is built for engineers who want to give remote agents durable, authenticated hands on a Unix box. The README is explicit: the primary deployment path is a hardened Streamable HTTP endpoint, not local stdio. Local clients like Claude Code, Codex CLI, Cursor, and VS Code are supported via stdio, but the design centers on remote access. If you are running an agent entirely on your laptop with no network exposure, Winx is overkill. It is for teams that need a bridge between cloud agents and a local development environment.

## The Architecture: Adapter, Guardian, and Unified Engine

The architecture separates the MCP adapter from the processes that own each PTY. On Unix, `winxd` manages the control plane, and one `winx-guardian` per logical session keeps the shell alive across HTTP disconnects and client restarts. The README's diagram shows a remote client sending HTTPS with a bearer token through a Secure MCP Tunnel or VPN, hitting loopback at 127.0.0.1:8000/mcp. The request passes through host/body/timeout checks, per-IP rate limiting, and a global concurrency cap. Principal authentication validates the token, and thread_id and MCP Task IDs are scoped internally. The shared WinxService then handles workspace coherence and file evidence, plus a unified mutation engine. This design means a stateless HTTP request maps to a durable session keyed by principal and workspace. Repeated `Initialize` calls reattach to the existing guardian instead of spawning a new one. That is the core innovation: the shell survives network failures, and the model sees a continuous session.

## Getting It Running: Commands and Config Keys

The quickstart is straightforward. Install with `cargo install winx-code-agent`. Create a token file with `install -m 600 /dev/null ~/.config/winx-http-token`, then generate a token with `openssl rand -hex 32 > ~/.config/winx-http-token`. Launch the server with `winx-code-agent serve --http --bind 127.0.0.1:8000 --token-file ~/.config/winx-http-token`. Clients connect to `http://127.0.0.1:8000/mcp` with an `Authorization: Bearer` header. The README stresses that cloud clients need a reachable HTTPS endpoint, so you must put a tunnel or reverse proxy in front. For OpenAI products, it recommends the Secure MCP Tunnel. The token file must be chmod 600, and the token must be at least 32 bytes. These are concrete, enforceable constraints, not suggestions. The default binding is loopback-only, which is a fail-closed choice. You can also run in stdio mode for local clients, but the docs point to the HTTP guide for that.

## Durable Sessions and Identity Isolation

The session model is what separates Winx from a simple MCP server. HTTP is stateless from the client's view, but the PTY lives in a guardian process that persists. The README says that repeated stateless `Initialize` calls reattach instead of manufacturing a new guardian. This is critical for long-running tasks like interactive debugging or a build that takes minutes. The identity model is also deliberate: one token per principal, and thread IDs and MCP Task IDs are scoped internally and translated back before the response leaves the server. Workspace affinity absorbs unstable model-generated thread IDs. That means two different principals cannot see each other's sessions, and a flaky model that changes thread IDs will still land in the right workspace. This is a real design choice, not an afterthought. The cost is that you must manage multiple tokens if you have multiple users, and the README mentions optional multi-principal TOML config, but the quickstart only shows a single token.

## The Unified EditFiles Engine: One Mutation Tool

Winx consolidates file editing into a single tool called `EditFiles`. The README describes it as creating, editing, batches, patches, verifying, and undoing through one typed plan/commit engine. This removes overlapping choices that plague other agents, where you have separate tools for write, patch, and apply. The engine preserves read evidence, canonical path binding, atomic writes, receipts, and recovery. That is a strong claim, but the docs support it. The trade-off is that you must learn a single, more complex interface. If your team already has scripts that call individual edit tools, moving to Winx requires adapting to the plan/commit model. The README also mentions repository-aware code navigation with tree-sitter symbol navigation, but the truncated section does not give details on how that integrates with EditFiles. You would need to read the architecture docs to see the exact API.

## Security Defaults and Their Implications

Winx ships with fail-closed network defaults. Loopback-only binding, 32-byte minimum tokens, chmod-600 token files, DNS-rebinding host checks, body/time/concurrency limits, per-IP rate limiting, and delayed invalid-auth responses. These are not common defaults. Delayed invalid-auth responses are a nice touch to slow down brute force. The README explicitly says to keep Winx on loopback and use a private tunnel or VPN. That is the right advice, but it means you must set up and maintain a tunnel. The security model also includes identity-aware isolation, so each principal has its own token and session scope. However, the README does not specify how the multi-principal TOML is structured. You will need to read the HTTP guide and SECURITY.md for that. The fail-closed posture is a genuine strength, but it also means the initial setup is not zero-config. You must generate tokens, set permissions, and configure a tunnel before anything works.

## Limitations and Wrong Tool Cases

The most obvious limitation is that the durable session model and guardian processes are Unix-only. The README says 'On Unix, Winx separates the MCP adapter from the processes that own each PTY.' There is no mention of Windows support for the guardian architecture. If your development machine runs Windows, Winx is not the right tool. Another limitation is the complexity of the process split. Running `winxd` and one `winx-guardian` per session means more moving parts than a simple stdio server. If you only need a local agent in VS Code, the guardian layer is wasted complexity. The README also notes that streamable HTTP is the main path, so if you rely on a cloud client that does not support streamable HTTP, you may be out of luck. The token file approach is secure but annoying for teams that rotate credentials frequently. Finally, the unified EditFiles engine is powerful, but it forces a specific workflow. If your team has invested in a different edit protocol, migration is not trivial.

## Alternatives and Maintenance Considerations

The README states that Winx started as a Rust port of WCGW, a Python-based tool. That is the most direct alternative. WCGW is a Python implementation, and the README claims Winx is not a wrapper: `cd` persists, `Ctrl+C` interrupts the real process, interactive TUIs work, and large terminal output is token-budgeted. If you are already using WCGW, the difference is the Rust implementation, the guardian process, and the streamable HTTP focus. Other MCP servers exist, but they often lack durable PTY sessions. The maintenance cost of Winx is tied to its release cadence. The repository shows frequent releases, with v0.2.343, v0.2.342, and v0.2.341 pushed on consecutive days. That suggests active development, but also that you will need to track updates regularly. The license is MIT, which is permissive, but you should verify the exact terms in the LICENSE file. The SECURITY.md is mentioned, so you should read it before deploying. The README also points to docs/architecture.md for invariants, which is where you would learn about upgrade paths. There is no explicit upgrade guide in the README, so you will need to check the release notes or the docs directory.

## Conclusion

Adopt Winx if you run cloud-based MCP clients like ChatGPT and need a real, stateful shell on a Unix development machine with strict network defaults and per-principal isolation. Skip it if you only need local stdio integration and prefer a lighter tool without the daemon/guardian process split. Before adopting, verify the token file permissions, test the loopback-only binding with your intended tunnel or reverse proxy, and confirm that the unified EditFiles engine matches your team's existing edit workflows. Winx is a serious, security-conscious option for remote agent operations, but its complexity and Rust-specific deployment are not for every setup.

## FAQ

### What are code agents, in the sense this runtime assumes?

An agent here is a client speaking the Model Context Protocol that needs a real shell, guarded file editing primitives and repository-aware code navigation. The runtime supplies those through four tool catalog profiles, a single guarded edit tool that plans and commits, and token-budgeted reads with tree-sitter symbol navigation.

### How do I activate agent mode in Visual Studio Code with winx?

The repository documents no editor agent mode. It lists Visual Studio Code among the local clients that use the stdio transport, where the client launches the agent binary itself and the process boundary is local, with a single local client sharing the same durable daemon runtime.

### How do I install winx-code-agent and expose it to a remote MCP client?

Install it with cargo, create the configuration directory, create an owner-only token file, write thirty two random bytes of hex into it, then start the server with the HTTP subcommand, a loopback bind address and that token file. A client connects to the single MCP path on that address with the file contents as a bearer token, and a tunnel or authenticated proxy goes in front for cloud clients.

### Does winx lose my shell when the HTTP connection drops?

No, and that is the point of the guardian process. Each logical session has a separate guardian that owns its pseudoterminal, the control plane manages those sessions, and the interprocess link is a Unix domain socket or, on Windows, named pipes plus job objects. A session is resumed with the same thread identifier, and repeated initialize calls reattach rather than creating a new shell.

## Sources

- [Official documentation](https://crates.io/crates/winx-code-agent)
- [Official README](https://github.com/gabrielmaialva33/winx-code-agent#readme)
- [Project repository](https://github.com/gabrielmaialva33/winx-code-agent)
- [Release notes](https://github.com/gabrielmaialva33/winx-code-agent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gabrielmaialva33-winx-code-agent