wisp

Safety-first automation and app QA through CLI and MCP, with an experimental desktop Hub.

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 headless artifacts remain an unsigned preview until the live qualification and signing gates pass.

Interface	Status	Intended use
wisp CLI and wisp-mcp (Linux)	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 on Linux
wisp CLI and wisp-mcp (Windows 11 x64, real-desktop)	Unsigned preview	Headless package with native broker capture, UI Automation, and guarded input
wisp-gui Electron Hub	Experimental	Optional desktop presentation for the same underlying runtimes

“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 on Linux and the Windows real-desktop preview.

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

1. 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.

2. Confirm the resolved configuration without driving anything:

   wisp --providers
   

3. 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, settled structured terminal frames, exact text grids, optional PNG evidence and private recordings	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.

Terminal and TUI QA

tui_open runs an interactive command in an isolated named tmux pane. Use tui_wait_for, tui_wait_idle, or tui_wait_exit instead of fixed sleeps; tui_status reports lifecycle, exit code, geometry, cursor, idle time, and recording state. tui_capture returns backward-compatible text by default and can also return a versioned styled-cell frame or PNG evidence. Resizing is confirmed through tui_resize, and tui_send accepts legacy text/keys or ordered typed input atoms.

Terminal evidence is explicit because it may contain prompts, output, or input secrets. tui_save writes owner-private text, JSON, ANSI, or PNG artifacts. tui_record_start, tui_mark, and tui_record_stop create a bounded private NDJSON timeline; tui_export_video renders it through ffmpeg when available. The experimental Hub exposes the same local pane as a live xterm with capture and recording controls.

SSH Companion

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

wisp-companion [email protected] "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 primary Windows artifact is the headless zip (wisp-<version>-win-x64.zip): CLI, MCP, companion entry points, and the native Rust broker for focused-monitor capture, UI Automation grounding, and guarded SendInput. An experimental Electron Hub package may also be built; it is optional and does not define Windows support.

On a Windows host only real-desktop is available. Nested sandbox, local tmux TUI/CLI, browser-tab, Android, and libvirt/Hyper-V host surfaces remain unavailable. Driving a Windows guest window from Linux with the real target exercises the Linux backend and does not qualify Windows.

Treat Windows support as a preview, verify artifact checksums, and use only a dedicated disposable machine or VM. Lab procedure: Windows lab. Maturity and promotion: Support.

REM on Windows, from the extracted headless package:
wisp.cmd --help
wisp-selftest.cmd winreal

Documentation

• Support and platform status
• Windows 11 headless lab
• Configuration reference
• Debugging and safe QA
• Security policy
• Privacy policy
• Contributing and release gates
• Roadmap and decisions
• Changelog
• License