winx-code-agent

What the runtime gives an agent

Winx is a remote first MCP runtime for agents that need a real shell, guarded file editing primitives, repository aware code navigation, and sessions that keep working after a dropped connection. It began as a Rust port of WCGW but is not a Python wrapper. The cd command persists between calls, Ctrl+C interrupts the real process, interactive terminal programs work, and large terminal output is rendered and trimmed to a token budget before it reaches the model. The primary deployment path is a hardened Streamable HTTP endpoint for ChatGPT and other cloud or networked MCP clients. stdio stays fully supported for Claude Code, Codex CLI, Cursor, VS Code, and other local clients. On Unix the design splits the MCP adapter from the processes that own each pseudo terminal. The winxd binary manages the control plane, and one winx-guardian per logical session keeps the shell alive across HTTP disconnects, client restarts, and adapter upgrades. A workspace can run in one of three modes. wcgw gives full access, architect is read only, and code_writer uses an allowlist of commands and write paths. The tool catalog can be narrowed further with the full, coding, read only, and terminal profiles, or an exact per principal allowlist, which reduces the schema payload and rejects calls outside the advertised set.

How the tool set is organized

Winx advertises MCP protocol version 2026 07 28. Every tool publishes an output schema and returns a shared structured content envelope while keeping its existing text or image content for older clients. The Initialize tool boots the workspace, picks the mode, and hands back a thread id. A local MCP client that exposes Roots can bootstrap the workspace automatically, otherwise the agent calls Initialize first. BashCommand runs commands, polls long running ones, sends Enter or Ctrl+C, and drives interactive terminal programs. ReadFiles reads one or many files with line numbers and accepts a range such as file.rs:10-40. FileWriteOrEdit does full overwrites or search and replace blocks, and it validates that the file was read and is fresh before writing. MultiFileEdit validates and computes every edit in memory before writing any file, so a failure leaves earlier files untouched. UndoEdit reverts the last edit per file. ContextSave writes a task summary plus file globs for clean handoff. ReadImage returns a native image block so multimodal models can see screenshots. CodeMap uses tree sitter to build a symbol map or look up where a name is defined and used across the repo, covering 11 languages. The status field is authoritative and tells the agent when a call is still running, awaiting input, or denied.

Why remote sessions stay safe

The Streamable HTTP endpoint binds to loopback by default and requires a strong bearer token, so it is not reachable from other machines unless you put a tunnel or proxy in front. A cloud client needs a reachable HTTPS endpoint, and the README suggests keeping Winx on loopback behind a private MCP tunnel, VPN, or authenticated reverse proxy. On OpenAI products a secure MCP tunnel keeps Winx private while exposing an OpenAI hosted endpoint. The server enforces a 32 byte minimum token length, chmod 600 token files, DNS rebinding host checks, body and time and concurrency limits, per IP rate limiting, and delayed responses to invalid auth. Repeated stateless Initialize calls reattach to the same durable session instead of spawning a new guardian. Secret redaction is on by default and scrubs provider API keys, JSON web tokens, PEM private key blocks, and user pass URLs from all tool output and saved memory. An opt in Landlock sandbox on Linux confines writes to the workspace and hides the home directory. The command allowlist is parsed with tree sitter, so it checks every command on a line, including pipelines and subshells, and cannot be bypassed by tricks like ls and curl piped to sh.

Editorial conclusion

Winx is a Rust MCP runtime installed with cargo install winx-code-agent and licensed under MIT. It pairs a Streamable HTTP endpoint with a stdio path so both remote and local agents get a durable shell and guarded file tools.