Install and connect

AgentWitch Local is the small app that runs your assistants on your own computer, and a computer is connected once that app is signed in to your account. This page covers installing it on a Mac, Linux or Windows, connecting more computers, keeping several accounts on one computer, updating, and removing it.

#What "this computer" means

"This computer" is the machine where AgentWitch Local runs. Your assistants work there, on your own folders. AgentWitch does not run them on hidden cloud machines. The Computers page lists every computer you connected, online or not.

The website and the app are separate:

The website (www.agentwitch.com) works in any desktop browser on any system. A Linux browser can sign in, read projects and send tasks.
The app must be installed on every computer that should run assistants.

So a Linux browser is not a Linux computer running the app. If your browser is on computer A and the app is on computer B, Computers shows B, but some things only work from a browser on B, such as picking a folder or scanning at once. If a page says "Scan runs on this computer. Open this page in a browser on the computer where AgentWitch is running.", do that. The This computer badge is only worked out from a Mac browser today.

#Install on a Mac

You need macOS 13 or newer. The Download page says the build is for Apple silicon (M1 and later).

Open www.agentwitch.com/download. It has three tabs: Download, Install and Set up.
Click Download for macOS.
Open the .dmg file and drag AgentWitch into Applications.
Open it from Applications. If macOS asks, choose Open. The app is signed by Developer ID and notarized by Apple.
Look for the wand icon at the top right of the menu bar. The app has no Dock icon.
Wait for setup: Checking this computer, Downloading the connection, Installing support for assistant tools, Checking everything works.

AgentWitch needs Node.js 20 or newer (22.13 or newer for every feature). Setup tries to install it, and says where to get it if that fails.

Run the app from Applications. From the disk image or a temporary folder, the Computer page shows Move AgentWitch Local to Applications. Quit, drag the app in, and open it from there.

Signing in. A fresh Mac can set itself up with no account. The Computer page then shows Trial on this Mac and Create an account. To connect an account you already have, click Sign in in the app, or Connect with the app on the website. Your browser opens, and if you are signed in it hands you straight back.

#Install on Linux

The Download page offers a 64-bit build (x86_64). It is not signed. On stock GNOME, turn on the AppIndicator extension, or the tray icon will not show.

On the Download tab, under Your computer, pick Linux. Choose Other Linux (AppImage) or Ubuntu/Debian (.deb) and download it.
For the AppImage, run chmod +x AgentWitchLocal-x86_64.AppImage, then ./AgentWitchLocal-x86_64.AppImage. For the .deb, use your package manager.
Sign in with the same account as in your browser.

Or install from a terminal: on Computers, click Connect this computer, copy the command and paste it into a terminal on that computer. Without a systemd user session, the installer says it is not running and prints the start command.

#Install on Windows

There is no Windows installer. AgentWitch runs inside WSL2.

On Home, in a Windows browser, click Set up AgentWitch on your computer.
Open PowerShell, paste the one line it shows, and press Enter. If you have no Ubuntu yet, the line installs it. Restart if Windows asks, then paste the same line again.
Open www.agentwitch.com. The computer appears as a Linux device.

If you already have a computer, Computers, then Connect another computer shows the command and says to install WSL first (wsl --install), open Ubuntu and paste it there.

#Connect another computer

On the new computer, open www.agentwitch.com and sign in with the same account.
Go to Computers and click Connect another computer (Connect this computer if you have none), then follow the steps for that system.

Each account has a limit on linked computers, and offline computers still count. At the limit, Computers suggests removing one you no longer use.

#Several accounts on one computer

One computer can carry more than one account. They stay separate, and adding one does not replace another.

In your browser, sign out, then sign in with the other account.
On Computers, click Connect another computer, then Connect with the app. The app opens your browser and connects that account.

Or, if you create a project with an account the Mac does not know yet, the page shows Allow this account on your Mac, and the Mac asks Connect (email) to this Mac? Click Allow, or Don't Allow if it was not you. With no answer for five minutes, nothing is added and the page offers Ask again.

If the app shows An account needs you to sign in again, click Sign in again under Settings, Account.

#Check that a computer is connected

On Computers, each row shows Online, Reconnecting or Offline.

In the Mac app, open Computer. It shows Running, Starting…, Problem, Waiting for internet or Stopped, and whether each assistant tool is Ready, Not signed in or Not installed. Click How to install or Log in, then Check again.

#Update

The Mac app checks once a day and installs an update by itself when its window is closed and nothing is running. To do it by hand:

In the app, go to Settings, then Updates.
Click Check for update. When a version is ready, click Restart to update. The app closes, updates and opens again.

The menu bar menu also shows Update when one is ready. On Computers, the row for the computer you are on has an Update button that gives you a command to paste into Terminal. For any other computer, update it from that computer. Update required on a row means it is too old for some features.

On Linux, Check for updates in the tray opens the Download page. You can also run this in a terminal. It keeps the computer linked:

curl -fsSL https://www.agentwitch.com/install/agent-witch-update.sh | bash

#Stop, restart and sign out

Stop or restart. On the Mac app's Computer page, click Stop or Restart. While stopped, assistants in every project cannot use the computer. On the website, a row's menu has Restart AgentWitch and Stop AgentWitch, but you cannot start a stopped computer from there. Start it on the computer.
Open at login. In Settings, under General, turn on Open at login. When it is off, assistants cannot use the computer until you open the app.
Sign out. In Settings, under Account, click Sign out…. Files stay. Assistants cannot use the computer until someone signs in and starts it.

#Rename, remove and reset

Rename or delete a computer. Open the row's menu on Computers. Edit renames it. Delete removes it from your account after you confirm. The computer disconnects, and your project folders and files stay. To use it again, open the app on it and sign in.
Remove the app. In the Mac app, go to Settings, find Remove for reinstall and click Remove…. It removes the sign-in, the device keys and the local app. Projects and reports stay. To start again, choose Start setup. From the website, use the row's On this computer menu, then Remove from this computer and Delete local install. The computer stays listed until you also choose Delete.
Repair. Choose Repair setup in the menu bar menu or in Settings. It reinstalls the local runner and keeps your projects, folders and settings.

#When connecting fails

Open www.agentwitch.com/setup/repair-this-computer. It walks through Update, Restart, Reconnect and a final check, and you stop when the check works.

In the Mac app, "Setup didn't finish" means click Retry setup, then Repair. AgentWitch cloud is unreachable means nothing is wrong on your computer, and it reconnects by itself. This computer is not linked to your account means click Reconnect.

#Query aliases

install AgentWitch Local on Mac
AgentWitch on Linux or Windows
connect another computer to AgentWitch
what does this computer mean
update or remove AgentWitch Local