wisp

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.

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

Related MCP server: GhostDesk

Choose an interface

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.

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

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.

Documentation

• Support and platform status

• Configuration reference

• Debugging and safe QA

• Security policy

• Privacy policy

• Contributing and release gates

• Roadmap and decisions

• Changelog

• License