wisp

<!-- docs-owner: usage --> <p align="center"> <img src="./assets/wisp.png" width="112" alt="wisp logo"> </p> <h1 align="center">wisp</h1> <p align="center"> Safety-first automation and app QA through CLI and MCP, with an experimental desktop Hub. </p> <p align="center"> <a href="https://github.com/grok-insider/wisp/actions/workflows/ci.yml"><img src="https://github.com/grok-insider/wisp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache 2.0 license"></a> </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](./SUPPORT.md) 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: ```bash nix run github:grok-insider/wisp -- --providers ``` Install the command suite into the current Nix profile: ```bash nix profile install github:grok-insider/wisp ``` Add wisp to a NixOS configuration: ```nix { 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: ```bash wisp --providers ``` 3. Start with an isolated nested-sway sandbox and the deterministic grid grounder: ```bash 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](#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. ```bash 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](./docs/reference/configuration.md) 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. ```json { "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. ```bash 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](./docs/architecture/companion.md). ## Headless panel and swarm ```bash 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](./SECURITY.md) and [Privacy](./PRIVACY.md) 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. ```bash 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](./docs/architecture/unified-hub.md) and the [roadmap](./PLAN.md). ## 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](./SUPPORT.md) for the complete capability list and promotion gate. ## Documentation - [Support and platform status](./SUPPORT.md) - [Configuration reference](./docs/reference/configuration.md) - [Debugging and safe QA](./DEBUGGING.md) - [Security policy](./SECURITY.md) - [Privacy policy](./PRIVACY.md) - [Contributing and release gates](./CONTRIBUTING.md) - [Roadmap and decisions](./PLAN.md) - [Changelog](./CHANGELOG.md) - [License](./LICENSE)