When AI Commander stops working

Four failures account for almost everything people write to us about, and the most destructive one — security software quarantining or deleting the agent — never mentions antivirus in any of its symptoms. That is what makes it hard to diagnose. Start from the symptom you are actually seeing — or let the machine tell you, by running the built-in diagnostics first.

Start by running the diagnostics

Before counting files, reading logs or reinstalling anything, have the machine describe itself. AI Commander ships a diagnostic run that checks the installation end to end — whether its files are present and intact, whether something on the machine has been interfering with them, whether it can reach the relay, whether autostart and the privileged helper are registered — and prints every check with a verdict and a remedy. It usually answers the question this page is here to answer in about ten seconds. It ships in the next release.

There are three ways in, and which one you have depends on how AI Commander was installed:

Desktop app: "Run Diagnostics…" in the tray

This is the one to use if you have the desktop app on Windows or macOS. Open the tray icon (Windows) or the menu-bar icon (macOS) and choose Run Diagnostics…. The checks take a few seconds — the menu row says so while they run — and then a dialog shows anything that failed, anything worth knowing, and a counts line reading so many OK, so many warnings, so many failed, so many not checked.

The dialog's buttons are Close, Copy Report and Save Report…, plus Open Help when something failed, which opens this page. Copy or Save gives you the report described below — Save proposes aicommander-diagnostics-<timestamp>.txt in your Downloads folder. On macOS it is written readable only by your account; on Windows it inherits the permissions of the folder you save it into, so put it somewhere only you can read if that matters on a shared computer. That file is what to attach to a support case or an antivirus vendor report; you do not need to go hunting for log files first.

Windows: the "AI Commander Diagnostics" Start-menu shortcut

The Windows installer also creates a Start-menu entry called AI Commander Diagnostics. It exists for the case this page is mostly about: the app's own folder has been emptied, so the tray icon and its Run Diagnostics… item are gone. The shortcut deliberately points somewhere else — at the privileged helper in the sibling folder %ProgramFiles%\AI Commander Privileged Helper, which the sweep did not touch — so it still runs when nothing in the application folder does.

It has no options and needs no administrator password. Because it runs outside your user profile it checks a deliberately smaller set — the helper's own files and registration, whether its endpoint answers, how many files the application install still has, and the watchdog's log — and it prints the list of what it did not check and where the full set lives. Read that list: a clean run here is not a clean bill of health for the whole installation. One check reports a warning when the shortcut is not run as an administrator, because it cannot inspect the installation folder's permissions from an ordinary account.

Headless and npm installs: aicommander-agent doctor

It prints every check with its verdict and, where a check is unhappy, what to do about it. Four flags:

It exits 1 if any check failed, and also if --report was given but the file could not be written; otherwise 0. Warnings and checks that were skipped do not make it fail. So a script can treat non-zero as "something needs a human", but not as "a check failed" — if you want that distinction, read the printed verdicts or --json, or leave --report off the run whose exit code you are testing. On a Linux service install, run it as the same user the service runs as (usually with sudo) so it looks at the service's own files rather than yours.

What the report contains

--report, Copy Report and Save Report… all produce the same thing: a redacted text report, redacted by construction rather than by filtering afterwards. It carries no access code, no agent token, no command text and no command output, and user account names are stripped out of every path. What it keeps is what a diagnosis needs — which files were where, which errors the operating system returned, and each check's verdict. That makes it safe to attach to a support ticket or to an antivirus vendor's false-positive form. It is still a description of your machine, so read it before you send it to a third party.

Blocked or quarantined by antivirus / endpoint security

Security software sometimes classifies the AI Commander agent as malicious and removes its files, blocks it from starting, or silently prevents it from reconnecting. This is a false positive. This section explains how to recognise it, fix it, and report it.

Symptoms

Any of these can mean your security software is the cause:

• The machine shows as offline in AI Commander, but the computer is switched on and online. It may have gone offline shortly after you ran a remote job.
• The app does not start. You launch it and nothing happens — no window, no tray icon, or the process appears and disappears within a second.
• The app crashes with Invalid file descriptor to ICU data received. This means core application files are missing from the installation folder.
• The installer runs, asks for an administrator password, and then disappears without installing anything. (This one has a second, more common cause.)
• "Access denied" when writing to the installation folder — including when you are signed in as an administrator, and even though the folder permissions look normal.
• Remote jobs stop working while everything else appears fine.
• Autostart stops working — the app no longer launches when you sign in, and the startup entry cannot be edited.

Why this happens

AI Commander is a remote administration tool. That is its purpose: it runs commands you send it, captures the screen when you allow it, transfers files, and keeps an outbound connection open so your machine can be reached.

Behavioural detection engines — Bitdefender Advanced Threat Defense, Microsoft Defender behaviour monitoring, and equivalents from ESET, Kaspersky, Norton, Sophos and others — score programs by what they do, not by what they contain. The behaviour above is close to indistinguishable from a remote access trojan, so the heuristic sometimes fires.

On Windows this most often targets the small helper scripts AI Commander writes when it runs a job:

wrapper.cmd is a fixed three-line file that runs the job, redirects its output to a log and records the exit code. It is identical for every job. command.cmd holds the command you asked the machine to run. Where that jobs folder is depends on which build you installed — see the exact paths, because excluding the wrong one is the most common way this fix fails.

Two consequences worth knowing:

• The detection is behavioural, not signature-based. Submitting the installer to your antivirus vendor will usually come back "no threat found", because the executable was never the thing that was flagged.
• Some engines respond by removing the application, not just the flagged script. This is why the app stops starting rather than simply warning you.

Quick check: is your security software the cause?

1. Count the files in the installation folder.

A healthy Windows installation contains around eighty files, including icudtl.dat, a locales\ folder with dozens of .pak files, several .dll files, and resources\app.asar.

If the folder contains only AICommander.exe, or is missing icudtl.dat or resources\, your security software removed the rest. A running executable is locked by Windows and cannot be deleted, which is why that one file often survives while everything around it is taken.

2. Test whether the job scripts survive being written (Windows).

This is the closest you can get to watching the detection happen, and it is what the built-in diagnostics do: stage the event a behavioural engine actually scores — a .cmd file appearing in the folder AI Commander writes its job scripts to — and then check whether it is still there a moment later. Open the jobs folder for the build you installed, create a folder inside it named probe, and save a text file there called command.cmd containing one harmless line:

Wait about ten seconds and look again. Read the result carefully — the two possible failures do not mean the same thing:

If the save was refused, save a plain probe.txt into the same folder with the same tool, containing the same line. That single extra observation separates the two causes: if the .txt saves and the .cmd does not, the only difference is the file itself and something is judging it — treat that as the detection. If neither saves, the folder is refusing you for ordinary reasons and your security software is not implicated at all; fix the access first (or run the built-in diagnostics, which report what they could and could not check) and do not add exclusions on the strength of this test.

Delete the probe folder afterwards.

3. Look in your antivirus quarantine.

Search it for anything under @aicommander or aicommander. Entries pointing at wrapper.cmd or command.cmd confirm the diagnosis. Note the detection name shown next to them — you will need it when you report this.

How to fix it

Follow these in order. Steps 3 and 4 are the two that are most often skipped, and skipping either one makes the rest fail.

1. Restore the quarantined files

In your antivirus quarantine, restore anything belonging to AI Commander. If your product offers "restore and add exception" in one action, use it.

2. Add exclusions for both locations

Excluding the installation folder alone is not enough. The job scripts live in your user profile, and that is where most detections actually fire. Exclude the installation folder and the jobs folder for the build you are running.

Most exclusion dialogs reject environment variables such as %APPDATA% and require a full literal path. Note that your profile folder name is not always identical to your account name — check the actual folder under C:\Users\.

Choose the option that covers on-access / real-time scanning, not only scheduled or on-demand scans.

3. Add a separate exception in the behavioural engine

This is the step people miss. On most products, antivirus file exclusions and the behavioural engine's exceptions are two different lists, and a file exclusion does not stop a behavioural detection.

Add the application executable itself to that list.

4. Restart the computer

Until the machine is restarted you may still see "Access denied" on the installation folder, on startup registry entries and on scheduled tasks — all of it while running as an administrator.

5. Reinstall

Download a fresh installer and run it. If the installation folder still exists but is incomplete, remove or rename it first.

6. Reconnect

Start AI Commander and let it reconnect on its own — it keeps its own session code across reinstalls, so there is nothing to type in and no pairing to redo. On Windows and macOS, open the app from the Start menu or Applications and look for the tray or menu-bar icon; on Linux, run sudo systemctl restart aicommander-agent.

If it does not come back online, quit the app completely and start it again, and check that the machine has ordinary outbound HTTPS to aicommander.dev — a proxy that does not pass WebSocket upgrades is the usual culprit. Then run the diagnostics: the connectivity checks say which leg of the connection failed, which is the difference between a firewall problem and a leftover block.

Confirm the machine shows as online again.

Reporting the false positive to your antivirus vendor

Reporting it helps every other user of that product. Vendors act on these, but only if the report contains the right material — and a bare copy of the installer is usually not enough.

Include:

• The detection name exactly as shown in your quarantine.
• A statement that it is a behavioural detection, not a signature match, so it reaches the right analysts.
• The flagged sample, which is wrapper.cmd. Do not send your own command.cmd files — they contain the commands you ran. Generate a harmless one instead by running a job such as echo test and sending that.
• Diagnostic logs from the vendor's own support tool, if they have one. For a behavioural detection this is the only artefact containing the event trace.
• AI Commander's own diagnostic report — run the diagnostics and use Save Report… (desktop app) or aicommander-agent doctor --report ./aicommander-diagnostics.txt (headless installs). It shows the other side of the same minutes: which of our files went missing, which writes were refused and with what error, and whether the job-script probe survived. It is redacted by construction — no access code, no token, no command text, no command output — but it is still your file, so open it in a text editor and read it before you send it to anyone.
• The agent's log file, if the analyst asks for the raw event sequence — see where the log lives. The report above is usually enough on its own.
• The date and time of the detection, with your timezone. Analysts search their logs by timestamp.
• The impact, if files were deleted or the installation was broken. This distinguishes a nuisance alert from a destructive remediation and usually raises the priority.
• Your security product name and exact version.

Ask them to allowlist by publisher identity, not by file hash. wrapper.cmd is constant and can be hashed, but command.cmd differs for every job, so a hash-based allowlist fixes one case and fails on the next command you run.

Two practical notes on sending it: many mail providers block .cmd attachments outright, including inside archives, so rename samples to .txt and say so in your message. Some also block password-protected archives, in which case use a file-sharing link instead.

What to send us

If the steps above do not resolve it, contact support with:

• The diagnostic report. This is the single most useful thing you can attach, and it usually settles the diagnosis on its own. You do not need to find any files by hand:
  • Desktop app (Windows, macOS): tray or menu bar → Run Diagnostics…, then Save Report… and attach the saved file (or Copy Report and paste it into the email).
  • Windows, if the app will not start: Start menu → AI Commander Diagnostics, and copy what it prints.
  • Headless / npm agent: aicommander-agent doctor --report ./aicommander-diagnostics.txt, and attach that file.
  It is redacted by construction — no access code, no token, no command text and no command output.
• Which symptom from the top of this page you are seeing
• The name and version of your security software
• The detection name from your quarantine, if there is one
• Roughly when the machine went offline, and whether a remote job was running

If the diagnostics cannot run at all on that machine, send the file count from your installation folder (and whether icudtl.dat and resources\ are present) plus the agent's log instead, and say what happened when you tried to run them.

That is usually enough for us to confirm the diagnosis without further back-and-forth. Write to support@coderai.dev.

Where the diagnostic log lives

AI Commander keeps a small diagnostic log of its own: startup, connection attempts and why they failed, permission errors on its own files, jobs starting and finishing by identifier, and whether the installation still contains the files it shipped with. It is a plain text file, one event per line. Find it here:

The headless agent runs as two processes and writes one file for each, so send both. The log folder always sits next to the jobs folder for the same install; if a path above does not exist on your machine, look beside the jobs folder you excluded earlier. AICOMMANDER_CONFIG_DIR does not move the desktop app's log, which always stays in the app's own data folder.

The machine shows offline but the computer is on

A machine is online when its agent holds an open outbound connection to the relay. "Offline" therefore means one of two things: the agent is not running, or it cannot reach the relay. Check them in that order.

1. Is the agent running?

• Windows / macOS. Look for the tray or menu-bar icon. If it is missing, launch the app.
• Linux. Run systemctl status aicommander-agent. If the unit is not there, the agent was installed in foreground mode and stops when the terminal closes — see the Linux agent.

2. Did it stop right after a remote job?

That is the fingerprint of a behavioural detection: the per-job helper scripts are written at the moment a job starts, so the engine fires then. If the app will not launch, or the process appears and disappears, go to the antivirus section and count the files in the installation folder before reinstalling.

3. If the agent is running, it is the network.

The agent needs outbound HTTPS to aicommander.dev and nothing else — no inbound port, no VPN. The usual blockers are a proxy that does not pass WebSocket upgrades, an egress firewall rule, or simply a machine that was asleep. Restart the agent (systemctl restart aicommander-agent, or quit and reopen the desktop app) and watch whether it reconnects. If it does not, run the diagnostics — its connectivity checks walk the connection one leg at a time and name the one that failed.

Windows ran the installer as a different account than yours

The password prompt Windows shows before an installer runs can hand the installer to a different account than the one you are signed in with — someone standing over your shoulder typing their password, or your own second administrator account. Older AI Commander installers handled that case badly and exited in complete silence, installing nothing. The current installer notices and says so before the wizard's first page: it tells you that this is what the password prompt was for, names the folder AI Commander is going into, and asks whether to continue.

Choose OK and the installation goes ahead normally, machine-wide, for every account on the computer. Cancel stops it without installing anything.

There is nothing to change afterwards. The notice is informational — it exists because a password prompt followed by silence used to be the whole experience, not because the install lands wrong. Windows hands the finished app back to the account you are signed in with, so first-run setup registers autostart for you, not for the administrator whose password was typed. If you are ever unsure, the tray menu's Start at login shows the current state.

You cannot predict the notice in advance from group membership. The installer compares the account Windows elevated it into with the account that started it — so an administrator who elevates with a second admin account sees it, and there is no net localgroup check that tells you either way.

If the installer still vanishes with no message at all, you are either running an older installer — download a fresh one — or something is blocking it. Check %ProgramData%\AICommander\install.log, which the current installer writes from its first moment, and if the installation is there but incomplete, treat it as a security-software block and work through the antivirus section.

The app does not start, or crashes with "Invalid file descriptor to ICU data received"

Both of these mean the same thing: files are missing from the installation folder. icudtl.dat is loaded at startup, and the app cannot run without it — so the process either dies immediately with no window and no tray icon, or exits with:

This is not a configuration problem and there is no setting to change. Open the installation folder and count what is there:

• A healthy Windows install has around eighty files, including icudtl.dat, a locales\ folder full of .pak files, several .dll files, and resources\app.asar.
• If it contains only AICommander.exe, or is missing icudtl.dat or resources\, something removed the rest — and on Windows that is almost always security software.

Do not reinstall over the top. Whatever removed the files is usually still enforcing the block, so the reinstall will fail or be stripped again within minutes. Work through the fix steps in order — restore, exclude both folders, add the behavioural exception, restart, and only then reinstall.

Troubleshooting FAQ

Why did my antivirus quarantine or delete AI Commander?

Because AI Commander is a remote administration tool, and behavioural engines — Bitdefender Advanced Threat Defense, Microsoft Defender behaviour monitoring, and the equivalents in ESET, Kaspersky, Norton and Sophos — score a program by what it does rather than by what it contains. Running operator-supplied commands, capturing the screen, transferring files and holding a persistent outbound connection open is close to indistinguishable from a remote access trojan, so the heuristic occasionally fires. It is a false positive, not a compromised build. On Windows the detection usually targets the small helper scripts the agent writes for each job — wrapper.cmd and command.cmd — rather than the signed executable, which is why submitting the installer to the vendor comes back clean. Some engines then remove the whole application instead of just the flagged script, which is why the app stops starting rather than merely warning you.

Does Bitdefender block AI Commander?

It can. Bitdefender's Advanced Threat Defense flags the per-job helper scripts AI Commander writes on Windows, quarantines them, and in some cases removes most of the files in C:\Program Files\AICommander as remediation. The fix is to restore the quarantined items, exclude both the installation folder and the folder the job scripts live in, add a separate exception in Advanced Threat Defense itself — antivirus exclusions and behavioural exceptions are two different lists — restart the computer so the kernel filter drivers reload, and only then reinstall and reconnect. The restart is not optional: until it happens you will still see access-denied errors while running as an administrator.

Which folders should I exclude from antivirus scanning?

Two, not one. Excluding the installation folder alone is not enough, because most detections fire on the per-job scripts in your user profile. Exclude C:\Program Files\AICommander, and then the jobs folder for whichever build you run: the desktop tray app writes to C:\Users\<you>\AppData\Roaming\@aicommander\desktop\jobs, and the headless agent installed from npm writes to C:\Users\<you>\AppData\Local\aicommander\jobs. If the headless agent runs with AICOMMANDER_CONFIG_DIR set, its jobs live in a jobs subfolder of that directory instead. On macOS the desktop app's jobs are in ~/Library/Application Support/@aicommander/desktop/jobs. Most exclusion dialogs reject environment variables such as %APPDATA% and require a full literal path, and your profile folder name is not always identical to your account name.

How do I run AI Commander's diagnostics?

It depends on how you installed it. With the desktop app on Windows or macOS, open the tray or menu-bar icon and choose "Run Diagnostics…", which lists what failed and offers Copy Report and Save Report. On Windows, if the app itself will not start, use the Start menu shortcut "AI Commander Diagnostics": it runs from the separate privileged-helper folder beside the application, so it still works when the application folder has been emptied, and it checks a smaller set and prints what it did not check. If you installed the headless agent from npm, run aicommander-agent doctor in a terminal — optionally with --report <path> to write a report file, --offline to skip every check that touches the network, --json for machine-readable output, or -v to show each check's facts; it exits 1 when any check failed, and also when --report was given but the file could not be written. A desktop installation does not put aicommander-agent on your PATH, so use the tray item or the Start menu shortcut there instead. The report all three produce carries no access code, no token, no command text and no command output, and strips user account names from paths, so it is safe to attach to a support case.

My machine shows offline but the computer is switched on — why?

The agent is either not running or cannot reach the relay, so check the machine itself first: on Windows and macOS look for the tray or menu-bar icon, and on Linux run systemctl status aicommander-agent. If the app is not there at all, or the process starts and disappears, security software is the most likely cause — especially if the machine went offline shortly after a remote job ran, which is when the flagged helper scripts are written. Count the files in the installation folder before reinstalling: a healthy Windows install has around eighty of them, and a folder containing only AICommander.exe means the rest were removed. If the agent is running, the remaining causes are ordinary ones: no outbound HTTPS to the relay, a proxy that does not pass WebSocket upgrades, or a machine that was asleep.

The installer asks for an administrator password and then nothing happens.

That symptom is not antivirus, and the current installer no longer produces it. It happens when Windows elevates the installer into a different account than the one you are signed in with — the administrator whose password was typed. Older installers exited silently at that point; the current one notices, and before the wizard's first page it says that this is what the password prompt was for, names the folder AI Commander is going into, and asks whether to continue. Choose OK and it installs machine-wide, for every account on the computer; Cancel stops it without installing anything. There is nothing to change afterwards: Windows hands the finished app back to the account you are signed in with, so first-run setup registers autostart for you and not for the administrator whose password was typed. Whether you see the notice depends on which account Windows elevated into, not on whether your own account is a local administrator — an administrator who elevates with a second admin account sees it too, and no command predicts it in advance. If the installer still vanishes with no message at all, you are running an older installer — download a fresh one — or something is blocking it, in which case work through the antivirus section.

AI Commander crashes with "Invalid file descriptor to ICU data received".

That error means core application files are missing from the installation folder — specifically icudtl.dat, which the app loads at startup. It is not a configuration problem, and reinstalling over the top usually fails because whatever removed the files is still enforcing the block. Check the installation folder: if it is missing icudtl.dat, the locales folder, or resources\app.asar, your security software deleted them. Restore the quarantined items, add the exclusions, restart the computer, and only then reinstall.

Troubleshooting guide published 2026-09-02 · Short link for vendor reports: aicommander.dev/antivirus · Desktop jobs folder: %APPDATA%\@aicommander\desktop\jobs · Headless agent jobs folder: %LOCALAPPDATA%\aicommander\jobs · Support: support@coderai.dev