Installation

wigolo runs anywhere Node.js 22+ runs. npm is the primary channel; Docker images are published for container setups, and single-file binaries (no Node.js needed) are attached to each GitHub Release. Homebrew and a hosted install script are packaged in the repo and publish with an upcoming release — they're listed at the bottom so you don't chase an artifact that isn't live yet.

npm / npx (primary)

No install needed — npx resolves the published package:

npx wigolo init

Or install globally:

npm install -g wigolo
wigolo init

init performs a complete setup by default (browser engine + on-device models + verification, with a per-component report). Pass --no-warmup to defer downloads to first use. See getting started for the init walkthrough.

Single-file binary

Each GitHub Release attaches a self-contained executable per platform — no Node.js install required:

Every asset has a matching .sha256 file, and SHA256SUMS.txt lists them all. Download, verify, and run (macOS Apple silicon shown):

curl -LO https://github.com/KnockOutEZ/wigolo/releases/latest/download/wigolo-macos-arm64
curl -LO https://github.com/KnockOutEZ/wigolo/releases/latest/download/wigolo-macos-arm64.sha256
shasum -a 256 -c wigolo-macos-arm64.sha256
chmod +x wigolo-macos-arm64
./wigolo-macos-arm64 init

On Linux use sha256sum -c instead of shasum -a 256 -c. The binary takes the same subcommands as the npm package; with no arguments it starts the MCP server on stdio, so point your MCP client at the binary's path.

The binaries are not yet code-signed. If you download one in a browser, macOS may block it on first run (allow it under System Settings → Privacy & Security, or run xattr -d com.apple.quarantine wigolo-macos-arm64), and Windows SmartScreen may warn before running it.

Docker

The published image is ghcr.io/knockoutez/wigolo. It's the slim variant: the browser engine binary and on-device models download on first use into the /data volume, keeping the image small and the downloads persistent.

MCP over stdio (one local client):

docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

Wire it into an MCP host, e.g.:

claude mcp add wigolo -- docker run -i --rm -v wigolo-data:/data ghcr.io/knockoutez/wigolo

HTTP daemon (remote MCP + REST, /health endpoint, multi-client) — use the compose file at packaging/compose.serve.yml:

docker compose -f packaging/compose.serve.yml up

The compose file binds 0.0.0.0 inside the container, which is a non-loopback bind: the daemon fails closed and refuses to start until you set WIGOLO_API_TOKEN (uncomment the line in the file) or explicitly opt into open access. Details in self-hosting.

The published browser-preloaded image is ghcr.io/knockoutez/wigolo:latest-full; versioned releases use the same -full suffix (for example, 0.3.1-full). It is useful for --rm/no-volume runs where first-use browser downloads would repeat:

docker run -i --rm ghcr.io/knockoutez/wigolo:latest-full

For local builds, the repo's Dockerfile exposes the corresponding full build target:

docker build --target full -t wigolo:full .

The named volume persists the local cache, on-device models, the browser engine binary, and encrypted keys across restarts.

MCP bundle (.mcpb)

The repo ships an MCP bundle manifest under mcpb/ for desktop hosts that support one-click MCP bundle installs. Prebuilt .mcpb artifacts publish with an upcoming release; until then, npm is the recommended path for desktop hosts too.

MCP registries

wigolo carries registry manifests at the repo root — smithery.yaml, glama.json, and mcp.json (a plain MCP server config you can copy) — and is listed on MCP directories including Glama and Smithery.

Agent auto-wire

wigolo init --agents=<csv> (or wigolo setup mcp) writes the MCP server entry — and, where the host supports them, instructions and skills — for these targets:

npx wigolo init --agents=claude-code,cursor

If your agent prompts for permission on every wigolo tool call after wiring, see troubleshooting.

For OpenCode, wigolo writes the global ~/.config/opencode/opencode.json entry in OpenCode's local MCP format:

{
  "mcp": {
    "wigolo": {
      "type": "local",
      "command": ["npx", "-y", "wigolo"],
      "enabled": true
    }
  }
}

Cline isn't an --agents target — wire its MCP entry by hand (next section) and it still gets the full skill packs via wigolo skills add.

Any other MCP host

Point it at the stdio server with this config block (this is exactly what ships in mcp.json):

{
  "mcpServers": {
    "wigolo": {
      "command": "npx",
      "args": ["-y", "wigolo"]
    }
  }
}

For hosts that speak HTTP instead of stdio, run wigolo serve and use http://127.0.0.1:3333/mcp — see the REST API.

Uninstall

npx wigolo uninstall

Removes all agent integrations: the MCP server config, the global instructions block, installed skills, and the slash command. It deliberately does not remove ~/.wigolo (cache, models, keys). Full cleanup:

rm -rf ~/.wigolo

Coming with a future release

These channels exist as source in packaging/ but their published artifacts are not live yet — the install commands below will not work until they are:

• Install script — packaging/install.sh, a POSIX bootstrap that installs under ~/.wigolo with a pinned, checksum-verified runtime (no root, no system packages).
• Homebrew — a formula at packaging/homebrew/wigolo.rb; the public tap is not yet published.

← Docs index · Next: Configuration