A little
untangling.

Start with the details

Note your app version (Settings → About), operating system, installation type, and the steps that trigger the problem. Check the backend log or Developer Tools for the relevant error. In a source run, look at the terminal output too.

If you report an issue, include a small example that shows it, and remove keys, personal paths and private content from logs.

Startup issues

“Backend Start Failed”, a blank window or a loading screen that stays

The backend or the frontend server couldn't start. Check these in order:

1. Are ports 8716 (backend) and 8717 (frontend) free? On macOS or Linux run lsof -i :8716 -i :8717; on Windows run netstat -ano | findstr "8716 8717". Find out what the process is before you stop anything, and close a second copy of Asyncat if one is running.
2. Read the backend log. In an installed build it is logs/backend-process.log in Asyncat's user-data folder; the error dialog's Open diagnostic logs button opens it, and Files → Logs & caches lists it. From source, it is den/logs/backend-process.log.
3. Open Developer Tools with View → Toggle Developer Tools, and look for errors in the console.

If the backend crashes, the desktop app restarts it on its own. To restart it yourself, press Cmd/Ctrl+Shift+R or use the tray menu.

A native module fails to load in a source run

The backend runs with your system Node.js. Rebuild its native modules for that Node.js from the repository root:

npm rebuild better-sqlite3 canvas

Don't rebuild them against Electron: installed builds run the backend with their own bundled Node.js. Use a Node.js version the README supports (22.13+ or 24+), and if it changed, run npm install again.

The operating system blocks a beta installer

The macOS and Windows installers are unsigned. Confirm the download came from the official release and follow its platform notes. See installation notes.

Agents and Cats

No response from the model

Check the chat's model in the menu under the message box, and the provider in Customize → Models: its address, key and model. For a local server, make sure it and the model are running. Cloud accounts may have rate, credit or availability limits.

The agent doesn't use the tool you expected

Check the mode. Plan uses read-only tools, and runs only commands proven read-only. Action uses every tool and asks before risky ones. If you picked one of your agents, check its Capabilities: anything switched off isn't available to it. Models also differ in how well they call tools; try a smaller task to narrow it down.

Every command asks, every time

The command sandbox is on but can't start, so commands ask instead of running without it. See The command sandbox.

A run repeats itself

Stop the run and look at its last successful step. Make the task smaller, name the target more clearly, or work through a plan first. If it happens again the same way, include the repeated steps in a bug report.

A Cat didn't run

• Cats only work while Asyncat is running. Check Settings → General → When you close the window.
• A run missed by more than 12 hours, while Asyncat was closed or the computer asleep, is skipped. Its timeline says so.
• A daily limit may have been reached; the inbox says which. The Cat carries on the next day, or raise the limit under its Freedom.
• It may be waiting for your answer under Waiting for you at the top of the Cats page, or switched off.
• An email wake-up needs an email account in Settings → Connections.

See Cats.

The command sandbox

Settings → Privacy & safety → Commands the agent runs says whether the sandbox is working, and why not when it isn't.

“On, but it can't start”

• bwrap isn't installed: install bubblewrap from your package manager, then press Check again.
• AppArmor stops bwrap from running: Ubuntu 24.04 and later do this by default. Allow bwrap in AppArmor, as your distribution's documentation describes, then press Check again.
• The system turns off the user namespaces bwrap needs: commands keep asking first until the sandbox can start.

Windows has no command sandbox yet, so there commands ask first unless they are proven read-only.

Commands have no network

With Package registries only or Off, Linux needs socat for the limited network. Without it, commands get no network at all. Install socat from your package manager. With Package registries only, a registry that isn't on the list can be added under Other registries.

A dev server the agent started won't open in your browser

With Package registries only or Off, dev servers that commands start can't be opened in your browser. Switch Network for commands to Open while you need it.

A tool can't find your sign-in or key

Sign-ins and keys, such as ~/.ssh, look empty to commands. Under Folders commands can't read, press Allow on the one the tool needs. See Privacy & safety.

Local models

Confirm the runtime works on its own before connecting Asyncat. Check the server address, that the model is available, and whether another process is using the port. In Customize → Models → Language, check that the model is loaded or the local server is connected.

If inference is slow or fails for lack of memory, try a smaller model or a shorter context. Check the runtime's detected hardware acceleration and its logs, and keep enough memory free for both the model and your other applications.

Linux desktop

The tray icon is missing

Some distributions need an app indicator library:

sudo apt install libappindicator1
# or
sudo apt install libayatana-appindicator1

On Linux, Quick ask is in the tray menu rather than on a left-click.

Listening (voice input) doesn't set up

There is no ready-made whisper.cpp download for Linux. Install whisper.cpp with your package manager, then press Check again in Models → Voice. Reading answers aloud and making pictures set themselves up. See Voice & images.

Global shortcuts don't work on Wayland

On Wayland, global shortcuts may not reach apps. Bind Asyncat with --quick-ask in your desktop's keyboard settings; Settings → Shortcuts shows the exact command.

The AppImage doesn't start

An AppImage needs permission to run: chmod +x Asyncat-*.AppImage.

Connections & permissions

A connector doesn't work

Settings → Connections → Connectors shows each connector's status. A connector that downloads first waits for your OK; one that signs in needs you to finish signing in in your browser. If data/mcp.json isn't valid JSON, Settings says so; fix or remove the file. Check the service's own setup and access too. See Connectors.

Claude Code, Codex or an ACP agent isn't available

Customize → Agents → Coding agents shows whether each is installed and signed in. Sign in from a terminal with claude auth login or codex login, then check again. Asyncat doesn't install them for you. See Coding agents.

Desktop tools can't see or control the screen

Check your operating system's accessibility and screen recording permissions for Asyncat.

Still stuck? Search the issue tracker, or open a focused report with the details you collected.