Web mode — insightworker --web

A browser UI that wraps the same agent core as the CLI. Run it on your laptop or on a remote box (EC2, ECS, your dev VM); open a browser to interact. Designed for demos, executives, and anyone who'd rather click than type.

insightworker --web

What you get:

• Chat panel — talk to the agent the same way you would in the terminal. Text streams in via Server-Sent Events; tool calls and their results render inline.
• Apps sidebar — every local InsightWorker app (<workspace>/.insightworker/workflows/<name>/) shows up automatically. Click one to open its widget form.
• File manager — split-pane explorer of the server's filesystem with inline preview. Upload, create folders, delete, download. Useful when you're running the CLI on a remote box and want to manage local files without SSH.

Quick start

# 1. Install (skip if already installed)
curl -fsSL https://insightworker.com/install.sh | bash

# 2. From the directory you want to work in
insightworker --web

The CLI prints:

Web mode: http://127.0.0.1:8765
  Workspace:  <cwd>/.insightworker
  Renderer:   bundled (web bundle)
  Chat + apps + file manager — same agent as the REPL.
  Stop with:  /web stop   (or just quit the REPL)

Open the URL — that's it.

Layout

Running on a remote box

If business users on different boxes need to run these apps in a browser without each one running insightworker --web locally, consider InsightStudio — a multi-tenant SaaS marketplace built on top of the same bundles. Your engineering box runs insightworker --worker to join the farm; business users hit the Studio URL.

Otherwise the server binds to 127.0.0.1 by default — only reachable from the same machine. For a teammate or a demo, tunnel rather than expose:

# On your laptop, tunnel to the remote box
ssh -L 8765:127.0.0.1:8765 user@your-ec2-host

# Then on the laptop, browse to:
#   http://localhost:8765

The file manager will show the remote box's filesystem (since the server is running there), which is usually what you want — you want to see, upload to, and pull from the server, not your laptop.

If you really need to bind to a public interface, set the host explicitly:

INSIGHTWORKER_WEB_HOST=0.0.0.0 insightworker --web

Put it behind a reverse proxy with auth. The built-in server has no auth on purpose — loopback by default.

Apps in the sidebar

An app shows up if you have a directory at:

<cwd>/.insightworker/workflows/<name>/

with at least one of:

• widget.json — declarative form schema (renders as a UI)
• workflow.yaml — task list the agent will execute
• tasks.md — free-form spec the agent will follow

Click an app:

• With widget.json → opens the app runner modal. Fill the form, hit Run. The agent executes the steps and streams outputs into the declared panels.
• Without widget.json → drops a context prompt into the chat referencing the app folder. The agent reads the spec from there.

Apps in InsightWorker are not Airflow DAGs. They live locally in your workspace. Airflow tooling is a separate, optional integration — see the tools overview.

File manager

File paths are constrained to the working directory the CLI was launched from (the "folder root") — you can't escape upward with .. paths. Symbolic links that point outside get rejected.

Cancellation

Any in-flight chat turn or app run can be cancelled:

• From the chat input — the send button turns into a Cancel button while a turn is streaming.
• From the app modal — the Run button becomes Cancel mid-run.
• From the API — POST /api/cancel with { "run_id": "..." }. The CLI uses this internally; you can use it from another shell.
• Implicit cancel — closing the browser tab aborts whatever is running.

Cancellation propagates through the provider SDKs (Bedrock, Anthropic, OpenAI, Gemini, Vertex) via AbortSignal, so the LLM stops streaming as soon as the cancel lands — you're not charged for tokens that come in after.

Authentication

There isn't any. The web server binds to 127.0.0.1 and trusts whoever's on the host. If you tunnel via SSH, your SSH session is the auth boundary. If you expose it publicly, add a reverse proxy with auth — Caddy, nginx + basic auth, Cloudflare Access, whatever you already use.

Troubleshooting

Port already in use. Another insightworker --web is running. Either /web stop in the existing REPL or pick a new port: insightworker --web --port 8766.

"App not found" when clicking. Check that the app folder has at least widget.json or workflow.yaml. Empty folders are skipped.

The agent says "I can't connect to Airflow" when I click an app. You're on a build older than 2.1.0 (current: 2.1.11). Upgrade: curl -fsSL https://insightworker.com/install.sh | bash. From 2.1.0 onward (current: 2.1.11), clicking an app opens its widget directly rather than routing through the chat agent.

See also

• Widget runner — how widget.json schemas drive the form-and-panel UI
• Apps & scheduling — overview — the YAML side of apps
• Install — CLI

Source: docs/interactive-ui/web-mode.md in the public repo. Open a PR with corrections.