Upgrade

On macOS and Linux, install the latest package and run setup again. Setup is required: it updates registrations with your AI tools and replaces the background process still serving the previous version.

npm install -g @opscanvas/opscanvas
opscanvas setup

On Windows, stop and unregister the current installation first, because Windows can prevent npm from replacing a running program:

opscanvas uninstall
npm install -g @opscanvas/opscanvas
opscanvas setup

Troubleshooting

The opscanvas command is not found

Open a new terminal after installing. If the command is still missing, check that npm’s global directory is on your PATH: normally $(npm prefix -g)/bin on macOS and Linux, and the directory reported by npm prefix -g on Windows. Node version managers keep global packages separate for each Node version, so install and run OpsCanvas with the same active version. If npm reports a permissions error on macOS or Linux, use a user-owned npm global directory or a Node version manager. Do not run OpsCanvas as root.

OpsCanvas does not appear in my AI tool

Run opscanvas setup (npm installation alone does not register OpsCanvas), then start a new session in your AI tool. Setup registers only supported tools it finds on your computer.

The background process is unavailable

opscanvas service status
opscanvas service restart

If restart works but OpsCanvas does not come back after you log in again, run opscanvas setup to repair the service registration.

The program file cannot be downloaded

Check that your operating system and architecture are supported, then check firewall and proxy access. Set HTTPS_PROXY and NO_PROXY where required. An air-gapped computer needs an internal mirror set through OPERATOR_BINARY_BASE_URL.

An upgrade still runs the old version

Run opscanvas setup after the npm installation. Setup replaces the running background process; npm alone does not.

Uninstall

Run these two commands, in this order, on any operating system:

opscanvas uninstall
npm uninstall -g @opscanvas/opscanvas

The order matters. opscanvas uninstall unregisters OpsCanvas from every AI tool, removes its hooks, skill, and approval, stops the background process, removes its service registration, and clears downloaded program files. npm uninstall -g then removes the launcher. Running only the npm command can leave the background process running and hooks active in your AI tool sessions.

Data kept after uninstall

Uninstall deliberately keeps your OpsCanvas data and prints its location:

  • macOS: ~/Library/Application Support/opscanvas/operator
  • Linux: ${XDG_CONFIG_HOME}/opscanvas/operator, or ~/.config/opscanvas/operator when XDG_CONFIG_HOME is not set
  • Windows: %LOCALAPPDATA%\opscanvas\operator

Delete that directory if you also want to erase the data.

Confirm removal

Run npm -g list. @opscanvas/opscanvas should not appear. A terminal that ran opscanvas before may remember the old command path; open a new terminal, or run hash -r in Bash.