---
app: agent
audience:
  - owner
since: 0.1.0
ui_only: true
agent_actions: []
agent_examples:
  - macOS says Bakulai Agent is damaged
  - Windows blocked the installer
  - the AppImage does not start
llm_weight: normal
title: Install problems
description: macOS says the app is damaged, Windows blocks the installer, an
  AppImage will not start, the setup stalls, or the office never appears.
editUrl: true
head: []
template: doc
sidebar:
  order: 1
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { Aside } from "@astrojs/starlight/components";
import { UiOnly } from "@components";

**Who this is for:** anyone stuck between the download and the first sight of the office.

<UiOnly />

## Why your computer warns you at all

Bakulai Agent is not yet distributed through the App Store, and its installers carry no Apple notarisation or Microsoft certificate. macOS and Windows therefore treat the first launch as "unknown software" and ask you to confirm it once. Updates afterwards are different: the app only accepts updates signed with Bakulai's own key.

## macOS

**"Bakulai Agent is damaged and can't be opened. You should move it to the Trash."**
Nothing is damaged. macOS marks every downloaded file with a quarantine flag, and for an app it cannot verify it shows this message. Two ways out:

1. Open it once (the warning appears), then go to **System Settings → Privacy & Security**, scroll to the security section, and press **Open Anyway**; confirm with Touch ID or your password.
2. Or remove the quarantine flag from that one app in **Terminal**:

   ```bash
   xattr -dr com.apple.quarantine "/Applications/Bakulai Agent.app"
   ```

   Then open the app normally.

<Aside type="caution" title="Only for apps you chose to install">
  That command tells macOS to trust one specific app. Never run it on something you did not deliberately download; it is not a setting to leave on, and it does not disable any other protection.
</Aside>

**"…can't be opened because Apple cannot check it for malicious software."**
Right-click (or Control-click) **Bakulai Agent** in Applications → **Open** → **Open** in the dialog. Once accepted, later launches are normal.

**The app will not start, or is extremely slow, on an Intel Mac.** Check which file you downloaded: `aarch64` is for Apple Silicon, `x64` for Intel. The wrong one either refuses to open or runs through translation.

## Windows

**"Windows protected your PC" (SmartScreen).** Click **More info**, then **Run anyway**. The message means the installer is not signed, not that anything was detected.

**Antivirus removed the installer.** Some third-party suites quarantine unsigned installers. Restore the file from the quarantine list, or allow it once, then install again.

**The window opens white and stays white.** The app draws itself with Microsoft's WebView2 component. Windows 11 has it; on Windows 10 the installer fetches it, so a blocked or offline install can leave it missing — reinstall while online.

**The Chat tab says the terminal needs WSL2.** Only that tab needs it. Install WSL2 (Microsoft Store → Ubuntu) if you want the terminal; automations, channels and everything else already work.

## Linux

**The AppImage does nothing when you double-click it.** Make it executable first: `chmod +x "Bakulai Agent_<version>_amd64.AppImage"`, then run it from a terminal so you can read any error.

**"dlopen(): error loading libfuse.so.2" or "AppImages require FUSE to run".** Install FUSE 2 — `sudo apt install libfuse2t64` on Ubuntu 24.04 and newer, `sudo apt install libfuse2` before that. Without it, run the file once with `--appimage-extract-and-run`.

**An error mentioning webkit2gtk.** The app needs **WebKitGTK 4.1**, which ships with Ubuntu 22.04+, Debian 12+ and Fedora 38+. On older distributions install `libwebkit2gtk-4.1-0` from the distribution's own repository, or use a newer release.

**You prefer a package.** A `.deb` is published next to the AppImage in each version folder.

## The setup after sign-in

**"Setting up Agent Hermes" stalls or crawls.** It downloads about 1.8 GB in total. Check free disk space (5 GB or more), and whether the network blocks `github.com` — the portable git comes from there. Restarting the app resumes from the stage it reached; nothing is downloaded twice.

**Setup stops at "Node".** The bundled Node.js could not start. Restart the app; if it stops again, Settings → Account & app → **Run agent health check**.

## After the setup

**You sign in and land on an upgrade screen.** Bakulai Agent is part of the **Pro** and **Max** plans; nothing is downloaded on other plans. See [Requirements](/agent/start/requirements/).

**The office never appears — a dark or empty window.** The 3D office needs **WebGL**. Virtual machines, remote-desktop sessions and very old graphics drivers often have none, and the app has no 2D fallback. Use a normal desktop session on the machine itself, update the graphics driver, or run the app on another computer — a [tablet](/agent/tablet/open-on-a-tablet/) can then reach that office.

## Related

[Requirements](/agent/start/requirements/) · [Install and sign in](/agent/start/install-and-sign-in/) · [An agent is not working](/agent/troubleshooting/agent-not-working/)