Winx Code 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 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 Unix, 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.

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

cargo install winx-code-agent

mkdir -p ~/.config
install -m 600 /dev/null ~/.config/winx-http-token
openssl rand -hex 32 > ~/.config/winx-http-token

winx-code-agent serve --http \
  --bind 127.0.0.1:8000 \
  --token-file ~/.config/winx-http-token

Connect an MCP client to:

http://127.0.0.1:8000/mcp
Authorization: Bearer

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 Unix 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 outside the advertised catalog.

• 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: guarded SEARCH/REPLACE edits, multi-file planning, undo, token-budgeted reads,

image input, context handoff, and tree-sitter symbol navigation.

Choose your transport

Remote architecture

Remote MCP client
       │  HTTPS + bearer token
       ▼
Secure MCP Tunnel / VPN / authenticated reverse proxy
       │  loopback HTTP
       ▼
127.0.0.1:8000/mcp
       │
       ├─ Host / body / timeout checks
       ├─ Per-IP rate limit + global concurrency cap
       ├─ Principal authentication
       └─ thread_id and MCP Task scoping
              │
              ▼
        shared WinxService
              │
              ▼
            winxd
              │
              └─ winx-guardian per session ── real PTY / shell / TUI

What you get

• A stateful bash session per thread with proper PTY semantics - foreground, background, status checks, text input,

Enter/Ctrl-C/Ctrl-D, raw ASCII. Multiline scripts and top-level command shorthand both work; NUL bytes are

rejected before they reach the shell.

• Workspaces with three modes: wcgw (full access), architect (read-only), code_writer (allowlist of commands and

write globs). The command allowlist is parsed with tree-sitter, so it checks every command on the line -

pipelines, &&/||/;, command substitution, subshells - not just the first word, and can't be bypassed with

ls && curl … | sh or ls $(rm …).

• A resilient PTY: a shell that won't return to a prompt (even after Ctrl-C) is auto-reset at the same cwd/mode, child

processes are reaped on drop, and prompt detection is robust to a custom PS1. Opt into zsh with WINX_SHELL=zsh.

• File reads with WCGW-style line ranges (file.rs:10-40, file.rs:10-, file.rs:-40). Active files are tracked

and prioritized in the repository context across calls.

• File writes and SEARCH/REPLACE edits that survive ambiguous matches, indentation drift, and the usual unicode

quote-mismatches from LLMs. Writes are blocked when the file hasn't been read or the cached content is stale, the

success message shows a compact diff of what changed, and recent edits are reversible with UndoEdit.

MultiFileEdit validates and computes every file before writing any of them, so a validation failure on the last file

leaves the earlier ones untouched. The commit phase uses atomic per-file renames; a rare mid-commit I/O failure stops

immediately but does not roll back files already written.

• Tree-sitter code navigation via CodeMap: a token-budgeted symbol map of a file or the whole repo, or a

definition/reference lookup for a symbol name - the semantic view that plain grep can't give you, across 11

languages.

• ContextSave for handing a task summary plus its files to the next session - including workspace context, active

files, git status/diff, and terminal sharing for proper resumption. Resuming reopens the saved project root and

token-caps the restored memory so it never overflows the context window.

• ReadImage so multimodal clients can pull screenshots, mockups, error PNGs, etc.
• Clean, token-aware shell output: cursor/ANSI noise from interactive programs (REPLs, progress

bars) is rendered away through a terminal emulator, and mechanical repetition is collapsed

losslessly (line [winx: ×N]) so build/install logs don't blow your context budget. Toggle the

collapsing with WINX_NO_COMPRESS. When output still overflows the cap, the dropped head is streamed

to a scratch file under .winx/scratch/ the agent can re-read, instead of being lost.

• Secret redaction on by default: provider API keys, JWTs, PEM private-key blocks and user:pass@ URLs

are scrubbed from all tool output and saved memory before they reach the model (disable with

WINX_NO_REDACT=1). An opt-in Landlock sandbox (WINX_SANDBOX=1, Linux) adds a kernel-enforced second

layer that confines writes to the workspace and hides the home directory.

• A hardened Streamable HTTP endpoint (winx-code-agent serve --http) for remote MCP clients, with stdio retained for

local tools. HTTP binds to loopback by default, requires a strong bearer token, limits request size/rate/concurrency,

and isolates sessions and MCP Tasks across authenticated principals - see the

deployment guide.

MCP Tools

Winx advertises MCP 2026-07-28. Every tool publishes an outputSchema and returns a shared

structuredContent orchestration envelope while preserving its existing text or image content for older clients. The

status field is authoritative (completed, running, awaiting_input, awaiting_approval, needs_read,

needs_initialize, conflict, not_found, denied, invalid_input, or failed). Recoverable failures are normal MCP

tool results with isError: true, retrySameCall: false, and (when Winx can infer one safely) a concrete nextAction plus

requiredReads. They are not opaque JSON-RPC errors, and agents should never repeat the rejected call unchanged.

BashCommand receives process state as a separate runtime-owned BashCommandState; rendered PTY output, child output,

and background-command metadata never feed orchestration decisions. Daemon protocol 1.5 transports that same typed

state and a separately rendered compact payload end to end, so marker-looking text cannot manufacture or suppress a polling loop. A ReadFiles batch with any

failed path is an honest isError: true result while retaining successfully read content; MultiFileEdit preserves

unread, stale, and SEARCH conflict recovery instead of flattening planning failures into generic invalid input.

Edit verification is bounded to 60 seconds and uses the same mode command policy as BashCommand. A non-zero exit returns

isError: true, errorCode: verification_failed, and data.edit_applied: true; it never falsely claims the edit was

rolled back. If the check is still running, the outer result supplies the normal BashCommand status_check next action.

MCP Tasks are optional on BashCommand and apply only to a foreground command; include an explicit thread_id and do

not combine the protocol-level task object with is_background=true. Routing is capability-driven: adaptive promotes

only after the inline runtime state is running, until_complete creates a Task immediately, and return_early never

does. Both client Task support and generation-bound runtime actions are required; protocol-1.4 guardians use the bounded

synchronous fallback. Task results retain the same structured envelope, are kept for the bounded TTL, and may be fetched repeatedly.

Daemon capability negotiation is bound to the effective guardian for that session and cached on an epoch-bound channel;

the control daemon's version or process name never enables Task promotion by itself.

Clients may explicitly advertise the io.winx/compact-bash-output extension to receive runtime-rendered Bash content

without the legacy textual status trailer; clients that omit it retain the existing text exactly.

On local stdio connections, a client that advertises MCP Roots can initialize Winx from its first usable

local file:// root. Winx never changes an active workspace after a Roots update. Automatic Roots bootstrap

is disabled on the shared HTTP service so one remote client cannot silently select another client's workspace.

Search/Replace editing

Standard block syntax:

>>>>>> REPLACE

Things the matcher forgives so you don't have to babysit the model:

• atomic: ambiguous or missing matches abort without touching the file
• adjusts replacement indentation when the LLM gets the leading whitespace wrong
• strips ReadFiles line numbers if they leak into a SEARCH block
• normalizes the usual "smart quote" / em-dash / ellipsis substitutions
• uses neighboring blocks to disambiguate when the same snippet appears twice
• single-line substring edits work - you don't need the whole line in SEARCH
• retries once with \" unescaped when the model over-escapes quotes in SEARCH
• refuses edits that only matched after too much fuzzy fixup, and rejects blocks

that match in too many places - so you re-read instead of corrupting the file

• anchor a block to a line number to pin one of several identical snippets -

`

Claude Code (CLI)

One-liner via the CLI (stdio is the default transport):

claude mcp add winx -- winx-code-agent

Or drop a .mcp.json in your project root:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Claude Desktop

Add to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Restart Claude Desktop after saving.

Codex (OpenAI CLI)

One-liner:

codex mcp add winx -- winx-code-agent

Or edit ~/.codex/config.toml:

[mcp_servers.winx]
command = "winx-code-agent"
env = { RUST_LOG = "winx_code_agent=info" }

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json for project-local):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

VS Code (Copilot Chat / MCP)

Add to .vscode/mcp.json:

{
  "servers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

Zed

Add to your Zed settings (~/.config/zed/settings.json):

{
  "context_servers": {
    "winx": {
      "source": "custom",
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

OpenCode

Add to opencode.json:

{
  "mcp": {
    "winx": {
      "type": "local",
      "command": ["winx-code-agent"],
      "enabled": true,
      "environment": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

agy (Google Antigravity CLI)

agy is Google's new Gemini-powered CLI (Go binary, usually at ~/.local/bin/agy). No mcp add subcommand yet - it

reads MCP servers from JSON.

Edit ~/.gemini/config/mcp_config.json (also ~/.gemini/antigravity/mcp_config.json if you run the Antigravity IDE

alongside):

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

If winx-code-agent is not on the agy process $PATH, swap command for the absolute path (~/.cargo/bin/winx-code-agent after cargo install winx-code-agent).

Continue.dev

Add to your ~/.continue/config.yaml:

mcpServers:
  - name: winx
    command: winx-code-agent
    env:
      RUST_LOG: winx_code_agent=info

Kiro

Add to ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

Warp

Settings → MCP Servers → Add MCP Server:

{
  "winx": {
    "command": "winx-code-agent",
    "env": { "RUST_LOG": "winx_code_agent=info" }
  }
}

Roo Code

Add to your Roo Code MCP config:

{
  "mcpServers": {
    "winx": {
      "type": "stdio",
      "command": "winx-code-agent"
    }
  }
}

Other clients (generic stdio)

Any client that speaks stdio MCP works with this shape:

{
  "mcpServers": {
    "winx": {
      "command": "winx-code-agent",
      "args": [],
      "env": { "RUST_LOG": "winx_code_agent=info" }
    }
  }
}

If your client launches Winx with an empty $PATH, swap command for the absolute path (

~/.cargo/bin/winx-code-agent).

Build from source

For unreleased changes or a custom build:

git clone https://github.com/gabrielmaialva33/winx-code-agent.git
cd winx-code-agent
cargo install --path .

Or build and run the complete Unix daemon bundle without installing:

cargo build --release --locked --bins
./target/release/winx-code-agent

For a quick in-process development run that deliberately skips winxd and winx-guardian:

WINX_EMBEDDED=1 cargo run --release

Check it's wired up

List MCP tools in your client. You should see nine entries: Initialize, BashCommand, ReadFiles, FileWriteOrEdit,

MultiFileEdit, UndoEdit, ContextSave, ReadImage, CodeMap. Start with Initialize unless your local client exposes

MCP Roots and Winx bootstraps from them; Winx tracks workspace + mode per thread.

Durable session lifecycle (Unix)

The daemon runtime caps live guardians at 32 by default and uses tiered idle retention: a shell that has never run a

command expires after 30 minutes, while a used shell expires after 24 hours. A foreground command or live background

command is never removed. New guardians report their own creation, activity, and command clocks; the control-plane JSON

beside each socket is only a permission-protected cache. For protocol-1.2 guardians, Winx uses real request metadata and

the socket birth time instead of treating a recreated tmpfs metadata file as fresh activity.

# Inspect and attach
winx-code-agent list
winx-code-agent attach  --follow

# Explicit cleanup
winx-code-agent kill 
winx-code-agent kill --all

# Apply the tiered defaults (30 min never-used / 24 h used)
winx-code-agent prune

# Override both tiers; zero removes every idle session but preserves active commands
winx-code-agent prune --idle-seconds 0

# Reload winxd after changing lifecycle environment variables; guardians survive
winx-code-agent restart-daemon

# Print a redacted configuration/runtime report
winx-code-agent doctor

The quota and TTL are enforced by winxd, not just by one MCP adapter, so reconnecting clients and multiple adapters

share the same resource boundary. Under quota pressure, Winx first reclaims the oldest inactive guardian that has never

run a command; used or active shells are never sacrificed to admit a new session. If no disposable guardian exists, the

error points to the effective force-prune command: winx-code-agent prune --idle-seconds 0.

A newly installed adapter upgrades an older control plane automatically when it advertises safe planned restarts; the

per-session guardians and their PTYs stay alive throughout. Protocol 1.3 introduced attach-or-create: repeating a first

call for the same key preserves the PTY, cwd, output journal, and running command. Protocol 1.4 adds

typed_action_result; protocol 1.5 adds optional compact_action_output and generation-bound actions. An older durable guardian remains inspectable, but BashCommand fails closed until that session is

removed and initialized again; Winx never reconstructs machine state from its terminal text.

Streamable HTTP deployment

Streamable HTTP is Winx's primary interface for ChatGPT, hosted agents, remote automation, and any MCP client that cannot

launch a local stdio process. The endpoint is always /mcp; the default listener is 127.0.0.1:8000.

Initialize returns a canonical thread_id/workspace_root pair. Every later remote stateful tool call must copy both

values unchanged. Winx validates the pair before selecting a PTY or touching a file, so a thread borrowed from another

chat/project fails closed. workspace_root is a session identity guard, not a containment boundary: with

WINX_ALLOW_PATHS=/, tools may still intentionally operate anywhere allowed by the active mode. A different project gets

its own pair through Initialize(first_call); remote sessions are never silently repointed in place.

Remote first calls default to --session-affinity workspace: the internal key is (principal, canonical workspace), so

reconnections and harmless variations such as release_02333 versus release_0_2_333 resolve to one guardian. Parallel

conversations from the same principal in the same repository therefore share one shell. Use `--session-affinity

conversation to key by principal + conversation + workspace: Winx prefers Mcp-Session-Id`, accepts a reviewed

X-Winx-Conversation-Id gateway header, and falls back to the supplied first-call thread_id. Use thread only when the

caller owns stable IDs and explicit cleanup.

[!TIP]

The full guide covers request headers, multi-principal configuration, private tunnels, operational limits, status codes,

durable sessions, troubleshooting, and the exact security boundary:

**docs/streamable-http.md**.

Deployment profiles

Multi-principal configuration

# ~/.config/winx-principals.toml
[[principals]]
name = "chatgpt"
token_file = "/home/alice/.config/winx-chatgpt-token"
tool_profile = "coding"

[[principals]]
name = "automation"
token_env = "WINX_AUTOMATION_TOKEN"
allowed_tools = ["Initialize", "BashCommand", "ReadFiles"]

chmod 600 ~/.config/winx-principals.toml ~/.config/winx-chatgpt-token
winx-code-agent serve --http \
  --principal-config ~/.config/winx-principals.toml

Each authenticated principal receives its own internal namespace. The same external thread_id can therefore be reused

by different clients without sharing a workspace, shell, guardian, or MCP Task. Internal prefixes are translated back out

of normal results and errors before the response reaches the client. tool_profile defaults to full; an

allowed_tools array replaces the selected profile. The policy applies to discovery and execution, not only display.

ChatGPT and OpenAI products

ChatGPT connects to remote MCP endpoints rather than directly launching a server on your machine. For private or local

Winx deployments, OpenAI documents the

Secure MCP Tunnel as an outbound-only path that avoids

opening inbound firewall ports. Developer Mode availability and workspace controls evolve, so use OpenAI's

current Developer Mode guide for the latest UI and plan

requirements.

HTTP defaults

Connector metadata

• Name: Winx
• Title: Winx High-Performance MCP
• Description:

Remote-first Rust MCP runtime that gives agents durable, authenticated access to a real PTY, guarded file editing,

token-budgeted reads, image input, and tree-sitter code navigation. Streamable HTTP supports multi-principal session and

Task isolation; stdio remains available for local clients.

The server advertises its icon in the initialize handshake (serverInfo.icons, MCP 2026-07-28). Source art lives in

[.github/assets/icon.png](.github/assets/icon.png).

[!WARNING]

A valid Winx principal is equivalent to shell and file access as the operating-system user. wcgw mode is intentionally

powerful and BashCommand is not workspace-confined. Keep HTTP on loopback, prefer private connectivity, use

architect or constrained code_writer sessions where possible, rotate leaked tokens, and stop the endpoint when it is

no longer needed.

Environment variables

All optional - Winx works out of the box without any of these. Boolean variables accept the same case-insensitive values:

1/true/yes/on and 0/false/no/off.

Verifying releases

Each GitHub release contains the platform artifact, its .sha256 file, an aggregate SHA256SUMS, and a CycloneDX JSON

SBOM. The workflow also publishes GitHub artifact attestations for the binaries and the SBOM relationship.

sha256sum --check winx-linux-amd64.tar.gz.sha256
sha256sum --check SHA256SUMS

Hacking on it

cargo fmt --all -- --check
cargo check --all-features --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features --locked
cargo +1.88.0 check --all-features --locked
cargo package --locked
cargo bench --bench performance --locked --no-run
cargo deny --all-features check
cargo audit --deny warnings
cargo +nightly fuzz build

To compare the ordered ReadFiles batch path with one versus four blocking workers on the current machine:

cargo bench --bench performance --locked -- read_files_batch

Criterion reports throughput and latency for both workers/1 and workers/4. Treat absolute numbers as machine-specific;

use the same host and power profile when comparing revisions. For production latency, enable WINX_USAGE_LOG and aggregate

the metadata-only duration_ms, response_bytes, batch_items, and worker_limit fields described in the HTTP guide.

CI runs these contracts in dedicated jobs, including the ignored real-PTY/TUI tests on Linux. If you touch PTY, terminal,

BashCommand, file editing, authentication, or persistence, run the focused regression suite before the full matrix.

Robustness is also fuzzed and model-checked:

• proptest feeds arbitrary/adversarial bytes into the live terminal emulator, the ANSI stripper, and the exit-code

parser, asserting they never panic and stay within the viewport. (This is how we found - and worked around - a vt100

underflow on tiny grids and a reflow panic on column shrink that would otherwise crash the panic = "abort" release.)

• loom exhaustively model-checks the session pin counter (the lock-free guard that keeps an in-flight session from

being LRU-evicted) across every thread interleaving. It's behind a feature so it doesn't perturb the normal build:

cargo test --features loom --lib loom_

A note on security

Winx supports local stdio and remote Streamable HTTP. Anything connected to either transport can read files, edit files,

and run shell commands with the capability granted by the selected mode - the same blast radius as giving the client a

terminal. HTTP extends that reach beyond the local process boundary; read the

Streamable HTTP deployment guide and SECURITY.md before exposing it.

Two things are on by default to reduce the blast radius: secret redaction scrubs high-confidence credentials

from all tool output and saved memory (WINX_NO_REDACT=1 to disable), and the PTY shell's whole process group is

killed on teardown so background jobs it spawned don't leak.

If you want a tighter leash:

• architect mode disables writes and most commands;
• code_writer mode lets you allowlist commands and write globs;
• WINX_SANDBOX=1 enables an opt-in Landlock filesystem sandbox (Linux): writes are confined to the workspace

plus /tmp, and the home directory is unreadable, so a manipulated agent can't read ~/.ssh/~/.aws or modify

files outside the project.

SECURITY.md has the disclosure process and threat model.

License

MIT – Gabriel Maia (@gabrielmaialva33)