> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Developing AgentUse for Mac

> Run, package, sign, and notarize the AgentUse macOS app

This page is for contributors working on the AgentUse Desktop app. For normal
installation and usage, see [macOS Desktop App](/guides/macos-desktop).

## Requirements

Desktop development requires:

* Node.js 22 or later
* Bun and pnpm
* Xcode, including its command-line tools

Xcode is required because the build compiles the native SwiftUI Settings helper
and uses Apple's asset-catalog compiler for the app icon.

## Run from source

From the repository root, install workspace dependencies, build the CLI and Web
UI, then start Electron:

```bash theme={"system"}
pnpm install
bun run build
pnpm desktop:dev
```

The Desktop process attaches to a registered `agentuse serve` daemon when one
is already running. Otherwise it starts the compiled local CLI on a loopback
port. The browser dashboard remains available at the URL shown in the menu.

Set `AGENTUSE_CLI_PATH` to test against a specific CLI build:

```bash theme={"system"}
AGENTUSE_CLI_PATH=/absolute/path/to/bin/cli.js pnpm desktop:dev
```

## Install a local build

For routine testing, install and launch one canonical app copy:

```bash theme={"system"}
pnpm desktop:install-local
```

The installer builds in temporary staging, gracefully terminates running
AgentUse Desktop copies, replaces `~/Applications/AgentUse.app`, and launches
that copy. Avoid opening `apps/desktop/dist/*/AgentUse.app` directly; using one
canonical installation prevents Launch Services from retaining several copies
with the same bundle identifier.

## Package the app

Create a package for the current Mac architecture:

```bash theme={"system"}
pnpm desktop:package:mac
```

For an unsigned development package:

```bash theme={"system"}
CSC_IDENTITY_AUTO_DISCOVERY=false pnpm desktop:package:mac
```

The Settings helper builds for the current architecture by default. For a
universal `arm64` and `x86_64` package, include both architectures in the nested
SwiftUI helper:

```bash theme={"system"}
AGENTUSE_SETTINGS_UNIVERSAL=1 pnpm desktop:package:mac
```

The package includes the AgentUse runtime, dashboard, built-in skills, and
required metadata. Source, tests, prior Desktop builds, and workspace caches are
excluded.

## Sign and notarize a release

For a manual release, store notarization credentials in the login Keychain so
the app-specific password does not enter shell history:

```bash theme={"system"}
xcrun notarytool store-credentials agentuse-notary \
  --apple-id <apple-id> \
  --team-id <team-id>

APPLE_KEYCHAIN_PROFILE=agentuse-notary pnpm desktop:package:mac
```

`notarytool` prompts securely for the app-specific password. electron-builder
uses the Developer ID Application identity installed in the login Keychain.

For CI, configure repository Actions secrets named `MAC_CSC_LINK` and
`MAC_CSC_KEY_PASSWORD`, plus `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, and
`APPLE_TEAM_ID`. The certificate value is the base64-encoded Developer ID
Application `.p12`. Keep all signing credentials in CI secrets. Hardened runtime
is enabled, and the packaged native Settings helper is placed under
`Contents/Frameworks` before notarization.

## Prepare an updater-enabled release

The root package and Desktop app share one release version. Use the repository
release script to prepare that version; do not edit the Desktop version
separately:

```bash theme={"system"}
bun scripts/release.ts prepare X.Y.Z
```

Push the prepared tag to the public repository. After the portable release gate
passes, GitHub Actions builds on native Apple Silicon and Intel runners. Each
package is signed, notarized, stapled, and verified before it is preserved as a
workflow artifact. The publishing job merges their update metadata and uploads
two DMGs, two Mac ZIPs, four blockmaps, and one `latest-mac.yml` to the release.
Every artifact filename includes `arm64` or `x64`, and the merged metadata lists
both architectures so electron-updater selects the matching ZIP.

Confirm the completed GitHub Release contains that nine-file set. Test the feed
from an older signed build on each architecture: confirm that the update
downloads in the background, choose **Later** in the native prompt, install it
from **Settings → About**, and confirm the new version launches. Repeat with
**Restart Now**, then repeat a check while offline and confirm the app continues
working while the About tab reports the failure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.