Skip to main content

Installation

Get DotAgents running on your machine in minutes.

One-Line Install​

The fastest way to get DotAgents on any machine:

curl -fsSL https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.sh | bash

This auto-detects your OS and architecture, downloads the latest release (macOS .dmg, Linux .AppImage, Windows .exe), and installs it. If no pre-built binary exists for your platform, it falls back to building from source.

Options:

# Force build from source instead of downloading a binary
curl -fsSL https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.sh | DOTAGENTS_FROM_SOURCE=1 bash

# Custom install directory (default: ~/.dotagents)
curl -fsSL https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.sh | DOTAGENTS_DIR=~/my-agents bash

Desktop App​

Download Pre-built Release​

Alternatively, download manually:

Download Latest Release

PlatformArchitectureFormat
macOSApple Silicon (M1/M2/M3/M4) + Intel.dmg (universal)
Windowsx64.exe installer
Linuxx64.AppImage, .deb
LinuxARM64.AppImage, .deb

macOS​

  1. Download the .dmg file from the releases page
  2. Open the .dmg and drag DotAgents to your Applications folder
  3. On first launch, right-click the app and select "Open" to bypass Gatekeeper
  4. Grant accessibility permissions when prompted (required for voice recording and text injection)

Windows​

  1. Download the .exe installer from the releases page
  2. Run the installer and follow the setup wizard
  3. DotAgents will appear in your Start menu

Note: Windows currently supports dictation-only mode. Full MCP agent functionality requires macOS. See v0.2.2 for Windows dictation builds.

Linux​

  1. Download the .AppImage or .deb package for your architecture
  2. For AppImage: chmod +x DotAgents-*.AppImage && ./DotAgents-*.AppImage
  3. For deb: sudo dpkg -i dotagents-*.deb

See the [Linux Support Matrix](https://github.com/aj47/dotagents-mono/blob/main/LINUX_SUPPORT_MATRIX for detailed platform compatibility.

Mobile App​

The DotAgents mobile app connects to your desktop instance or any OpenAI-compatible API endpoint.

Prerequisites​

  • Node.js 18+
  • Expo CLI: npm install -g expo (or use npx expo)
  • For native builds: Xcode (iOS) or Android Studio (Android)

Install from Source​

cd apps/mobile
npm install

Run on Device​

# Start Metro bundler
npm run start

# Or run directly on a device/simulator
npx expo run:ios      # iOS (requires Xcode)
npx expo run:android  # Android (requires Android Studio)

Important: The mobile app uses expo-speech-recognition, a native module not available in Expo Go. You must use a development build to run on physical devices. See the Mobile App guide for details.

Web​

The mobile app also runs in the browser:

npx expo start --web

Speech recognition on web requires Chrome or Edge over HTTPS.

Running from Source​

For contributors, or if you want the bleeding-edge development version.

Prerequisites​

ToolVersionInstall
Node.js24.x recommended (min 20.19.4)nodejs.org or nvm use
pnpm9.xnpm i -g pnpm
Ruststable (optional — needed for voice input binary)curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Xcodelatest (macOS only, for code signing)Mac App Store

pnpm is required. npm and yarn are not supported.

Clone & Run​

git clone https://github.com/aj47/dotagents-mono.git
cd dotagents-mono
nvm use                  # uses .nvmrc → Node 24.x
pnpm install
pnpm build:shared        # build the shared package first
pnpm dev                 # start the desktop app in dev mode

Build the Rust Native Binary (optional)​

The Rust binary powers native keyboard input and voice recording. Without it the app still runs, but those features won't work.

pnpm build-rs

Production Builds​

pnpm build              # current platform
pnpm build:mac          # macOS (Apple Silicon + Intel universal)
pnpm build:win          # Windows (x64)
pnpm build:linux        # Linux (host architecture)

Updating​

cd dotagents-mono
git pull
pnpm install
pnpm build:shared
pnpm dev

See the Development Setup guide for Docker builds, debug flags, and troubleshooting.

System Requirements​

RequirementMinimumRecommended
OSmacOS 12+, Windows 10+, Ubuntu 22.04+macOS 14+, latest Windows/Ubuntu
RAM4 GB8 GB+
Disk500 MB1 GB
Node.js (dev only)20.19.424.x
NetworkRequired for AI provider API callsBroadband for voice streaming

Next Steps​