Installation
Get DotAgents running on your machine in minutes.
One-Line Install
The fastest way to get DotAgents on any machine:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.ps1 | iex
These installers auto-detect your OS and architecture, download the correct release artifact, and install DotAgents without assuming Git, Node, pnpm, or Rust are already installed. Building from source is still available, but it is now an explicit opt-in.
Prefer a manual download? Use the latest release page for macOS, Windows, or Linux artifacts.
Need a terminal-only Linux setup? Use the source/headless installer option below, then see the Headless CLI reference for dotagents, /setup, /status, /config, and Discord commands.
Options:
# Force a source install instead of downloading a release (macOS / Linux)
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
# Force a source install on Windows
$env:DOTAGENTS_FROM_SOURCE = '1'; irm https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.ps1 | iex
# Custom install directory on Windows
$env:DOTAGENTS_DIR = "$HOME\dotagents"; irm https://raw.githubusercontent.com/aj47/dotagents-mono/main/scripts/install.ps1 | iex
Desktop App
Download Pre-built Release
Alternatively, download manually:
| Platform | Architecture | Format | Link |
|---|---|---|---|
| macOS | Apple Silicon (M1/M2/M3/M4) | .dmg | Latest macOS release |
| macOS | Intel | .dmg | Latest macOS release |
| Windows | x64 | .exe installer | Latest Windows release |
| Linux | x64 | .AppImage, .deb | Latest Linux release |
| Linux | ARM64 | .AppImage, .deb | Latest Linux release |
macOS
- Download the
.dmgfile from the releases page - Open the
.dmgand drag DotAgents to your Applications folder - On first launch, right-click the app and select "Open" to bypass Gatekeeper
- Grant accessibility permissions when prompted (required for voice recording and text injection)
Windows
- Download the
.exeinstaller from the releases page - Run the installer and follow the setup wizard
- DotAgents will appear in your Start menu
Windows builds include the desktop app, voice shortcuts, text input, provider setup, and agent features. Some OS-level integrations may differ from macOS; see the in-app diagnostics if a native permission or tool integration is unavailable.
Linux
- Download the
.AppImageor.debpackage for your architecture - For AppImage:
chmod +x DotAgents-*.AppImage && ./DotAgents-*.AppImage - For deb:
sudo dpkg -i dotagents-*.deb
See the Linux Support Matrix for detailed platform compatibility.
Uninstall
Linux one-line install
If you installed with the one-line installer, remove the app files and launcher:
rm -rf ~/.dotagents
rm -f ~/.local/bin/dotagents
If you used the Linux source/headless flow or VPS installer and created a systemd service, stop and remove it first:
sudo systemctl stop dotagents 2>/dev/null || true
sudo systemctl disable dotagents 2>/dev/null || true
sudo rm -f /etc/systemd/system/dotagents.service
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/dotagents
rm -rf ~/dotagents ~/.dotagents
rm -f ~/.local/bin/dotagents
If you installed the .deb package manually, uninstall the package instead:
sudo apt remove dotagents
macOS
Remove the app bundle:
rm -rf /Applications/DotAgents.app ~/Applications/DotAgents.app ~/.dotagents
Windows
Use Settings → Apps → Installed apps → DotAgents → Uninstall.
Remove local configuration and app data
The uninstall steps above keep your DotAgents settings, local conversations, and app data where the operating system stores application data. To fully reset DotAgents, remove the data directory for your platform:
# Linux
rm -rf ~/.config/app.dotagents
# macOS
rm -rf "$HOME/Library/Application Support/app.dotagents"
On Windows, remove %APPDATA%\app.dotagents from File Explorer or PowerShell if you want to delete local settings and data.
Mobile App
The DotAgents mobile app connects to your desktop instance or any OpenAI-compatible API endpoint.
Prerequisites
- Node.js 20.19.4+ (Node 24.x recommended via
.nvmrc) - pnpm 9.x
- For native builds: Xcode (iOS) or Android Studio (Android)
Install from Source
git clone https://github.com/aj47/dotagents-mono.git
cd dotagents-mono
nvm use
pnpm install
Run on Device
# Start Metro bundler
pnpm --filter @dotagents/mobile start
# Or run directly on a device/simulator
pnpm --filter @dotagents/mobile ios # iOS (requires Xcode)
pnpm --filter @dotagents/mobile 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:
pnpm --filter @dotagents/mobile 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
| Tool | Version | Install |
|---|---|---|
| Node.js | 24.x recommended (min 20.19.4) | nodejs.org or nvm use |
| pnpm | 9.x | corepack enable && corepack prepare pnpm@9 --activate |
| Rust | stable (optional — needed for voice input binary) | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
| Xcode | latest (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 --filter @dotagents/desktop build-rs
Production Builds
pnpm build # current platform desktop build
pnpm --filter @dotagents/desktop build:mac # macOS (Apple Silicon + Intel universal)
pnpm --filter @dotagents/desktop build:win # Windows (x64)
pnpm --filter @dotagents/desktop 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
| Requirement | Minimum | Recommended |
|---|---|---|
| OS | macOS 12+, Windows 10+, Ubuntu 22.04+ | macOS 14+, latest Windows/Ubuntu |
| RAM | 4 GB | 8 GB+ |
| Disk | 500 MB | 1 GB |
| Node.js (dev only) | 20.19.4 | 24.x |
| Network | Required for AI provider API calls | Broadband for voice streaming |
Next Steps
- Quick Start — Configure your first AI provider and start chatting
- Your First Agent — Create a specialized agent profile