---
sidebar_position: 1
sidebar_label: "Development Setup"
---

# Development Setup

Everything you need to build DotAgents from source.

---

## Prerequisites

| Requirement | Version | Purpose |
|-------------|---------|---------|
| **Node.js** | 24.x recommended (min: 20.19.4) | Runtime |
| **pnpm** | 9.x | Package manager (required) |
| **Rust** | Latest stable | Native keyboard/input binary |
| **Xcode** | Latest (macOS only) | Code signing |

> **pnpm is required.** Using npm or yarn will cause installation issues.

```bash
corepack enable
corepack prepare pnpm@9 --activate
```

## Quick Start

```bash
git clone https://github.com/aj47/dotagents-mono.git
cd dotagents-mono
nvm use
pnpm install
pnpm --filter @dotagents/desktop build-rs    # Build Rust native binary
pnpm dev         # Start development server
```

## Build Commands

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server (desktop) |
| `pnpm dev:mobile` | Start development server (mobile, Expo) |
| `pnpm build` | Production build for current platform |
| `pnpm --filter @dotagents/desktop build:mac` | macOS build (Apple Silicon + Intel universal) |
| `pnpm --filter @dotagents/desktop build:win` | Windows build (x64) |
| `pnpm --filter @dotagents/desktop build:linux` | Linux build for host architecture |
| `pnpm --filter @dotagents/desktop build:linux:x64` | Linux x64 build |
| `pnpm --filter @dotagents/desktop build:linux:arm64` | Linux ARM64 build |
| `pnpm --filter @dotagents/desktop build-rs` | Build Rust native binary |
| `pnpm test` | Run test suite |
| `pnpm test:run` | Run tests once (CI mode) |
| `pnpm test:coverage` | Run tests with coverage |
| `pnpm typecheck` | TypeScript type checking |
| `pnpm lint` | ESLint across all packages |

For signing, release packaging, GitHub Actions artifacts, docs builds, and web deployments, see [Build, Release, Deploy](build-release-deploy).

## Debug Mode

```bash
pnpm dev d               # ALL debug logging
pnpm dev debug-llm       # LLM calls and responses
pnpm dev debug-tools     # MCP tool execution
pnpm dev debug-ui        # UI state changes
```

See [Debug Reference](/reference/debug) for details.

## Docker

Build Linux packages in a consistent environment:

```bash
docker compose run --rm build-linux         # Build Linux packages
docker compose run --rm --build build-linux # Rebuild after code changes
docker compose run --rm shell               # Interactive dev shell
```

## Linux Architecture-Specific Builds

```bash
pnpm --filter @dotagents/desktop build:linux:x64
pnpm --filter @dotagents/desktop build:linux:arm64
```

Override packaging targets:

```bash
DOTAGENTS_LINUX_TARGETS=AppImage,deb pnpm --filter @dotagents/desktop build:linux:arm64
```

## Mobile Development

```bash
pnpm --filter @dotagents/mobile start    # Start Metro bundler
pnpm --filter @dotagents/mobile ios      # iOS (requires Xcode)
pnpm --filter @dotagents/mobile android  # Android (requires Android Studio)
pnpm --filter @dotagents/mobile web      # Web
```

## Testing

```bash
pnpm test                    # Watch mode
pnpm test:run                # Single run (CI)
pnpm test:coverage           # With coverage report
```

Tests use **Vitest** and are located alongside source files as `*.test.ts` and `*.test.tsx`.

## Troubleshooting

### "Electron uninstall" error

```bash
rm -rf node_modules && pnpm install
```

### Multiple lock files

```bash
rm -f package-lock.json bun.lock
rm -rf node_modules && pnpm install
```

### Windows: "not a valid Win32 application"

```powershell
pnpm install --ignore-scripts
pnpm.cmd -C apps/desktop exec electron-builder install-app-deps
```

### Node version mismatch

```bash
nvm use    # Uses the repository .nvmrc
```

---

## Next Steps

- **[Architecture Deep Dive](architecture)** — Technical details for contributors
- **[Build, Release, Deploy](build-release-deploy)** — Release packaging, signing, and deployment map
- **[Apps & Packages](apps-and-packages)** — Every app, package, and support area in the monorepo
- **[Contributing](contributing)** — How to contribute
