gabrielmaialva33/winx-code-agent

### *The High-Performance, Remote-First MCP Runtime for AI Coding Agents*
**Durable PTY Sessions • Streamable HTTP • Guarded File Operations • Blazing Fast Rust 🦀**
"Give remote and local LLMs durable, authenticated hands on your development machine."
⚡ Quickstart  • 
✨ Features  • 
🏗️ Architecture  • 
🌐 HTTP Guide  • 
🛡️ Security
English • Português • 中文
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 survive dropped connections. Its primary deployment path is a hardened
**Streamable HTTP** endpoint for ChatGPT and other cloud or networked MCP clients; stdio remains fully supported for
Claude Code, Codex CLI, Cursor, VS Code, and other local clients.
On Linux, macOS, and native Windows, Winx separates the MCP adapter from the processes that own each PTY. winxd
manages the control plane and one winx-guardian per logical session keeps the shell alive across HTTP disconnects,
client restarts, and adapter upgrades (Unix-domain sockets on Unix, named pipes plus job objects on Windows).
It started as a Rust port of WCGW, but it is not a Python wrapper: cd persists,
Ctrl+C interrupts the real process, interactive TUIs work, and large terminal output is rendered and token-budgeted
before reaching the model.
> [!IMPORTANT]
> **Streamable HTTP is the main deployment path.** Winx binds it to loopback by default, requires a strong bearer token,
> supports independent authenticated principals, and defaults to one durable session per principal/workspace. Repeated
> stateless Initialize calls reattach instead of manufacturing a new guardian.
Remote MCP in 60 seconds
Connect an MCP client to:
Cloud clients need a reachable HTTPS endpoint. Keep Winx on loopback and use a private MCP tunnel, VPN, or authenticated
HTTPS reverse proxy in front. For OpenAI products, the
Secure MCP Tunnel keeps Winx private while exposing
an OpenAI-hosted MCP endpoint.
**Next:** complete Streamable HTTP deployment guide ·
security model · local stdio setup
Why Winx for remote agents
- **Durable sessions:** HTTP is stateless from the client's point of view, but PTYs live in per-session guardians and
can be resumed with the same thread_id.
- **Identity-aware isolation:** one token per principal; 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.
- **Right-sized tool catalogs:** full, coding, read-only, and terminal profiles—or an exact per-principal
allowlist—reduce discovery/schema payloads and reject calls without equivalent effective authority.
- **One mutation tool:** EditFiles creates, edits, batches, patches, verifies, and undoes through one typed
plan/commit engine, removing overlapping choices while preserving read evidence, canonical path binding, atomic writes,
receipts, and recovery.
- **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.
- **Agent-native terminal semantics:** foreground and background commands, status polling, interactive input, stable TUI
snapshots, turn detection, real exit codes, and bounded output.
- **Repository tools, not just a shell:** one guarded edit protocol, multi-file planning, undo, token-budgeted reads,
image input, context handoff, and tree-sitter symbol navigation.
Choose your transport
| Transport | Best for | Endpoint / launch | Authentication | Session model |
|---------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------|----------------------------------------------------|------------------------------------------------------------------------------|
| **Streamable HTTP** | ChatGPT, hosted agents, remote automation, multiple MCP clients | https://host/mcp through a tunnel/proxy, with Winx on 127.0.0.1:8000 | Strong bearer token; optional multi-principal TOML | Stateless requests mapped to durable principal/workspace sessions by default |
| **stdio** | Claude Code, Codex CLI, Cursor, VS Code, desktop and local IDE clients | client launches winx-code-agent | Local process boundary | One local client, using the same durable daemon runtime |
Remote architecture
The detailed module boundaries, process contracts, and safety invariants are documented in