Installation

InsightWorker ships as a CLI and a Desktop app. Both share the same agent core.

CLI (recommended for engineers, SREs, devops)

One install line. Requires Node 18+. Runs everywhere Node runs (macOS, Linux, Windows via WSL/Git Bash).

curl -fsSL https://insightworker.com/install.sh | bash

What this does:

1. Installs Node 20 LTS if not present (Homebrew on macOS, NodeSource on Linux).
2. Installs the npm package globally — npm install -g @verticalserve/insightworker.
3. Creates ~/.insightworker/ with a starter .env and an empty workspace + skills folder.
4. Adds insightworker to your PATH.

Verify:

insightworker --version
insightworker -c "say hello"        # one-shot, no LLM call needed

If insightworker: command not found after install, your shell didn't pick up the new PATH. Open a new terminal or source ~/.zshrc (or ~/.bashrc).

Your first App — under a minute

Once the CLI is installed and at least one model provider is configured (see providers), scaffold and run your first §15 App without leaving the terminal:

mkdir -p ~/myworker && cd ~/myworker
insightworker

# In the REPL:
> /app create "convert docx files to pdf using libreoffice"
# → Scaffolded convert-docx-files-to-pdf (app.yaml, widget.json, workflow.yaml, plan.md)
# The agent then enriches each file with concrete content.

> /exit

Now run the App, three ways depending on what you need:

# 1. Headless one-shot — ideal for cron, CI, scripts.
insightworker app run convert-docx-files-to-pdf \
  --input docx_file=/path/to/resume.docx
# → newline-delimited JSON events on stdout
# → produced PDF lands in apps/<slug>/runs/<runId>/

# 2. Browser widget UI — fill a form, watch SSE progress, download outputs.
insightworker -c "/app run convert-docx-files-to-pdf --ui"
# → opens http://localhost:8765

# 3. Interactive REPL — let the agent walk through it conversationally.
insightworker
> /app run convert-docx-files-to-pdf

The workflow.yaml the agent scaffolded can mix LLM-driven prompt: steps with deterministic action: shell steps. The action: shell path runs as a plain script with no model in the loop — perfect for file conversions, ETL, and other I/O-shaped work. See Widget runner for the full step model.

Three flavors of the CLI

The same install gives you three ways to drive the agent — pick whichever fits the moment:

insightworker                            # interactive REPL (terminal)
insightworker --web                      # browser UI: chat + apps + file manager
insightworker /app create "<description>"  # generate a new app from a description

• REPL is the default for engineers. Type, get answers, hit /exit.
• --web is the demo / non-engineer surface. Opens a chat-style web app on 127.0.0.1:8765, with an apps sidebar and a file manager. Tunnel via SSH when running on a remote box. See Web mode.
• --ui opens a single app's declarative form in a browser. Fill the form, run, see live SSE panels. See Widget runner.

Desktop app (recommended for business users)

Download the right installer for your platform from insightworker.com/download:

• macOS Apple Silicon: InsightWorker-latest-arm64.dmg
• macOS Intel: InsightWorker-latest-x64.dmg
• Windows: InsightWorker-Setup-latest.exe

Trial builds are unsigned. On first run:

• macOS: right-click → Open → confirm. (Or xattr -cr "/Applications/InsightWorker.app" if Gatekeeper marks it as damaged after a download via browser.)
• Windows: SmartScreen may block — click "More info" → "Run anyway".

The Desktop app uses the same ~/.insightworker/.env for configuration as the CLI. They're interchangeable.

Manual CLI install (no script)

If you don't trust the install script (fair) or you're on a locked-down machine:

# Make sure Node 18+ is installed
node --version

# Install globally
npm install -g https://insightworker.com/releases/insightworker-latest.tgz

# Create the workspace dir
mkdir -p ~/.insightworker/workspace ~/.insightworker/skills

# Copy a starter .env (download from the install script)
curl -fsSL https://insightworker.com/install.sh | grep -A 200 'cat >.*ENVEOF' | head -200 > /tmp/iw-env-snippet
# Then paste the relevant block into ~/.insightworker/.env

Air-gapped / offline install

The npm tarball is self-contained — no further downloads needed at runtime once installed.

1. On a connected machine: curl -fsSL https://insightworker.com/releases/insightworker-latest.tgz -o iw.tgz
2. Move the .tgz to the air-gapped box.
3. npm install -g ./iw.tgz

The agent will fail to call any LLM provider unless you've also configured an in-region endpoint (Bedrock VPC endpoint, Azure private endpoint, or a custom on-prem inference server via LLM_PROVIDER=custom).

Updating

Re-run the install script — it removes the old version and clears the npm cache before pulling the latest.

curl -fsSL https://insightworker.com/install.sh | bash

Your ~/.insightworker/.env is never overwritten by the installer. If you want the latest defaults, diff against https://insightworker.com/releases/insightworker-latest.tgz's .env.example.

Uninstall

npm uninstall -g @verticalserve/insightworker
rm -rf ~/.insightworker        # WARNING: also deletes your local memory and saved playbooks

Troubleshooting

Source: docs/getting-started/install-overview.md in the public repo. Open a PR with corrections.