Skip to main content

​
macOS Desktop

Download the signed DMG from the latest GitHub release, open it, and move AgentUse to Applications. The app includes the AgentUse runtime and dashboard, so it does not require Node.js or a separate CLI installation. On first launch, Desktop setup offers two choices:
  • Launch AgentUse at login is selected by default and is applied when you select Continue.
  • Add CLI launcher optionally creates ~/.local/bin/agentuse for use in Terminal. Setup remains available even if you skip it.
After continuing, the app joins the same guided sample and first-agent flow as the Web UI.

macOS Desktop guide

Learn how the menu-bar app, CLI launcher, and login-shell PATH work together.

​
Requirements

These requirements apply to command-line installations. The macOS app bundles its own runtime.

Node.js

Node.js 22 or later

Operating system

macOS, Linux, or Windows with WSL
Check your Node.js version before installing:

​
Install the CLI globally

A global installation gives you the agentuse command in every terminal.

Continue to Quick Start

Create a project, run the built-in sample, and create your first agent.

​
Run without installing

Package runners download AgentUse into their cache and run it without adding a global command:
Use the same runner prefix for later commands. For example:
Install AgentUse globally if you expect to use it regularly.

​
Upgrade

The AgentUse Mac app downloads updates in the background and prompts when they are ready. Use Settings → About for a manual check or to install an update you deferred. See AgentUse for Mac for details. For command-line installations, run the install command again to move to the latest release:
Confirm which version your shell resolves:

​
Uninstall

Removing the CLI does not remove your projects or AgentUse configuration under ~/.agentuse.

​
Install from source

Use this path when contributing to AgentUse or testing an unreleased build. It requires Node.js 22+, Bun, and pnpm.
npm link points the global agentuse command at this checkout. Re-run pnpm build after source changes, or use the repository’s development scripts for watch mode.

​
Docker

You do not need Docker to use AgentUse. The official image is intended for self-hosting and containerized execution.

Self-hosting with Docker

Run the Web UI, webhooks, schedules, and agents in a container.

​
Troubleshooting

Confirm that your package manager’s global binary directory is on PATH:
Restart your terminal after changing PATH. You can also use npx agentuse@latest --version without changing your global installation.
AgentUse requires Node.js 22 or later:
With nvm, install and select Node.js 22:
Avoid installing with sudo. Use a Node.js version manager such as nvm or Volta, then retry the global installation.
Check which executable your shell resolves:
Remove an older installation made by another package manager, or put the intended package manager’s global binary directory earlier on PATH.
Use the terminal setup path on a remote, headless, or SSH environment: