MCP 服务器

wisp

Provides bounded, observable access to graphical apps, browsers, terminals, Android devices, virtual machines, and SSH hosts through MCP tools, enabling safe automation and app QA.

README

<p align="center"> <img src="./assets/wisp.png" width="112" alt="wisp logo"> </p>

<p align="center"> Safety-first automation and app QA through CLI and MCP, with an experimental desktop Hub. </p>

wisp gives agents bounded, observable access to graphical apps, browsers, terminals, Android devices, virtual machines, and SSH hosts. Use its provider-backed CLI for autonomous tasks or expose deterministic tools to an MCP client that already supplies the model.

The release-qualified host is NixOS x86_64 with Hyprland and Wayland. Other Linux environments may work when their runtime tools and permissions are equivalent, but are not release-qualified. See Support for the exact platform policy.

Product status

There is no published general-availability release yet. The signed v0.0.2 source and its draft artifacts are the current release candidate. Publishing that draft is a deliberate maintainer decision; Windows artifacts retain their separate unsigned-preview status until the live qualification and signing gates pass.

Interface	Status	Intended use
`wisp` CLI and `wisp-mcp`	Supported and release-tested	Autonomous tasks and model-controlled tools on the qualified Linux configuration
Companion CLI/MCP, `wisp-panel`, and `wisp-swarm`	Supported and release-tested	SSH operations, observable headless runs, and bounded parallel sandboxes
`wisp-gui` Electron Hub	Experimental	Optional desktop presentation for the same underlying runtimes
Windows 11 x64 real desktop	Unsigned preview	Native capture, UI Automation grounding, and guarded input through the packaged broker

“Experimental GUI” refers only to the Electron Hub and its React presentation layer. Visual automation through the CLI or MCP is part of the supported headless product.

Choose an interface

Start here	When to use it
`wisp "task"`	Let wisp plan and run one bounded task with your configured model provider
`wisp-mcp`	Give an MCP-capable agent explicit GUI, browser, mobile, VM, terminal, CLI, and inspection tools
`wisp-companion` / `wisp-companion-mcp`	Inspect and operate SSH hosts through a text-first, approval-aware path
`wisp-panel`	Watch a headless run through a capability-protected loopback panel
`wisp-swarm`	Run a bounded pool of isolated nested-sway tasks
`wisp-gui`	Evaluate the experimental all-in-one desktop Hub

Prefer semantic interfaces over pixels: browser_* for websites, tui_* for terminal applications, and cli_* for bounded commands. Use visual tools when the actual interface is graphical.

Install with Nix

The flake provides the packaged CLI, supporting binaries, an experimental gui app, and a NixOS module.

Try the packaged CLI without installing it:

nix run github:grok-insider/wisp -- --providers

Install the command suite into the current Nix profile:

nix profile install github:grok-insider/wisp

Add wisp to a NixOS configuration:

{
  inputs.wisp.url = "github:grok-insider/wisp";

  outputs = { self, nixpkgs, wisp, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      modules = [
        wisp.nixosModules.default
        {
          programs.wisp.enable = true;
        }
      ];
    };
  };
}

The module installs the Wayland and terminal runtime tools and can configure ydotool/uinput, AT-SPI, Android tools, and libvirt integration. Review its options before enabling real-desktop or guest control. Group membership changes require a new login session.

Safe quick start

Configure one provider from the table below. Wisp reads documented credential variables from the private ~/.config/wisp/env file as well as the process environment; never place that file in the repository.
Confirm the resolved configuration without driving anything:
```
wisp --providers
```

Start with an isolated nested-sway sandbox and the deterministic grid grounder:

WISP_TARGET=nested WISP_GROUNDER=grid \
  wisp "open the terminal and type hello from wisp"

The nested target cannot move the host cursor or type into host applications. Keep WISP_TARGET=real for deliberate runs on an idle desktop after reading the safety model.

Providers

Select a credential provider with WISP_PROVIDER.

Provider ID	Credential source	Transport
`xai-apikey`	`XAI_API_KEY`	OpenAI-compatible chat
`openrouter`	`OPENROUTER_API_KEY`	OpenAI-compatible chat
`anthropic-key`	`ANTHROPIC_API_KEY`	Anthropic Messages
`ollama`	Local endpoint	OpenAI-compatible chat
`custom`	`WISP_API_KEY` and an explicit `WISP_BASE_URL`	Configurable
`xai-oauth`	Existing Grok CLI credential store	Responses
`codex-oauth`	Existing Codex CLI credential store	Responses
`claude-oauth`	Existing Claude Code credential store	Anthropic Messages

API-key and local providers are the clean default. OAuth-reuse providers are explicit opt-ins: they reuse another CLI's subscription credentials and client identity, may conflict with provider terms, and remain pinned to their official hosts.

WISP_PROVIDER=xai-apikey WISP_MODEL=grok-4.3 WISP_TARGET=nested \
  wisp "inspect the sandbox"
WISP_PROVIDER=openrouter WISP_MODEL=provider/model WISP_TARGET=nested \
  wisp "inspect the sandbox"
WISP_PROVIDER=ollama WISP_MODEL=qwen3-vl:8b WISP_BRAIN_MODE=json \
  WISP_TARGET=nested wisp "inspect the sandbox"

Provider-native base URLs are selected automatically. WISP_BASE_URL can override API-key and custom providers; OAuth transports cannot be redirected. See the configuration reference for models, endpoints, timeouts, evidence, and safety gates.

Capabilities and prerequisites

Capability	Primary path	External prerequisite
Isolated Linux GUI	Nested sway with AT-SPI, VLM, or grid grounding	Qualified Nix package and a model provider for autonomous runs
Linux real desktop	Hyprland capture plus AT-SPI/VLM grounding and guarded input	Wayland session, ydotool/uinput permissions, and an idle desktop
Browser	Text-first accessibility snapshots and current element references	Chromium-compatible agent-browser runtime and an allowed host
CLI and TUI	Bounded processes and exact tmux text grids	`tmux` for interactive terminal applications
Android	adb capture/input and uiautomator grounding	Reachable, awake, user-unlocked device
Virtual machine	libvirt capture, QMP input, and optional QGA inspection	Running domain; absolute tablet for pointer input; QGA for guest execution
SSH and Companion	OpenSSH control channel plus optional interactive tmux terminal	Reachable SSH host and user-authorized credentials

The experimental Hub maps these runtimes to internal surface kinds: sandbox-app, real-desktop, android-device, vm-domain, tui-pane, cli-run, ssh-host, ssh-terminal, and browser-tab. Those identifiers are architecture vocabulary, not separate product tiers.

MCP

wisp-mcp speaks stdio MCP. The client supplies the model, presents its own per-tool approvals, and pays for its own model usage; direct MCP tool calls do not invoke wisp's autonomous provider.

{
  "mcpServers": {
    "wisp": {
      "command": "wisp-mcp",
      "env": {
        "WISP_MCP_ALLOW_REAL": "0",
        "WISP_MCP_ALLOW_VM": "0",
        "WISP_MCP_ALLOW_GUEST_EXEC": "0"
      }
    }
  }
}

Real-desktop, VM, and guest-execution capabilities remain unavailable until their corresponding gates are explicitly enabled. MCP resources expose redacted session evidence for inspection and debugging.

SSH Companion

Companion provides text-first, auditable remote operations without making the experimental Hub a requirement.

wisp-companion user@example.com "explain why the service is unhealthy"
wisp-companion --write web01 "restart the service"
wisp-companion-mcp

Commands, risk decisions, approvals, redacted output, and rollback hints remain visible. Interactive SSH uses one visible ssh -tt tmux pane plus a hidden control channel for context and integration discovery. Structured Docker, Kubernetes, and Coolify reads are offered only after the integration is detected and enabled. See the Companion architecture.

Headless panel and swarm

wisp-panel --hold --open "inspect the app"
wisp-swarm --open --task "check login" --task "check settings"

The panel prints a capability URL; the bare loopback address is intentionally insufficient. Swarm workers use isolated nested targets and retain the same approval and time limits as a single run.

Safety model

Real-desktop approval defaults to confirm-risky; missing, expired, or disconnected approval channels deny.
auto is not a supported real-desktop operating mode.
Human keyboard or pointer input pauses real automation before the next action.
A process-wide lease prevents concurrent processes from controlling the real desktop.
Actions, steps, runs, approvals, browser operations, and child processes have deadlines and active cancellation.
Model values are clamped, and untrusted strings never enter a host shell through interpolation.
The HUD, control socket, panel, and Hub provide independent stop paths where available.
Browser authentication sharing is off by default, loopback-CDP only, origin-scoped, and temporary.
Screenshots persist only when evidence logging is explicitly enabled.

Read Security and Privacy before enabling real-desktop input, guest execution, or browser authentication sharing.

Experimental desktop Hub

wisp-gui is an optional Electron and React interface over the same visual, browser, terminal, and Companion runtimes. It brings sessions, approvals, evidence, provider settings, and SSH connections into one window, but its end-to-end workflows and presentation layer are still experimental and are not part of the current supported-interface guarantee.

nix run github:grok-insider/wisp#gui

Do not use the Hub as the sole stop or approval path for safety-critical evaluation. Report GUI findings separately from CLI/MCP runtime issues. The architecture and promotion criteria live in Unified Hub architecture and the roadmap.

Windows 11 unsigned preview

The Windows x64 package pairs the experimental Hub with a native Rust broker for focused-monitor capture, UI Automation grounding, and guarded SendInput. It is unsigned and has not completed the live packaged Windows qualification checklist. Linux-only nested, terminal, browser, Android, SSH, and libvirt host surfaces are unavailable on Windows.

Treat Windows support as a preview, verify artifact checksums, and use only a dedicated disposable machine or VM. See Support for the complete capability list and promotion gate.