Running AiderDesk via npm (CLI)

AiderDesk can be installed and run as a global npm package. This runs only the AiderDesk backend service — there is no Electron desktop window. Instead, you access AiderDesk through your web browser, similar to running with Docker.

This is useful when you:

Prefer a lightweight setup without the desktop app
Want to run AiderDesk on a remote server
Need to integrate AiderDesk into scripts or CI/CD pipelines
Don't want to download a platform-specific installer

Installation

Install globally with npm:

npm install -g @aiderdesk/aiderdesk

Alternatively, run it directly without installing:

npx @aiderdesk/aiderdesk

During installation, the postinstall script automatically downloads the required uv Python package manager and probe binary for your platform.

Running

Interactive TUI (Default)

aiderdesk

This opens an interactive terminal UI where you can:

Start/Stop the service with s
Change port with p
Scroll logs with arrow keys or Page Up/Down
Exit with q or Ctrl+C

Headless Foreground

aiderdesk start

Runs the service in the foreground with logs printed to stdout. This is ideal for:

Docker containers
systemd services
CI/CD environments
Any environment where you need process output in the terminal

Options

Option	Description
`-p, --port <port>`	Set the port to listen on (default: `24337`)
`-h, --help`	Show help message
`-v, --version`	Show version number

Run a Prompt Non-Interactively

aiderdesk run "Explain what closures are in JavaScript"

Connects to a running AiderDesk server, sends the prompt, streams the AI response to your terminal, and exits when done. The current working directory is used as the project. If the project doesn't exist yet, it's automatically created.

You can also pipe input via stdin:

cat README.md | aiderdesk run "Summarize this file"

Options:

Option	Description
`-p, --port <port>`	Server port (default: `24337`)
`--host <host>`	Server hostname (default: `localhost`)
`-f, --format <format>`	Output format: `text` (default) or `json`
`-q, --quiet`	Suppress progress indicators
`-m, --model <provider/model>`	Override the model (e.g. `openai/gpt-4o-mini`)
`-a, --agent-profile <id>`	Use a specific agent profile by ID or name
`--task-id <id>`	Run on an existing task (multi-turn conversations)

See the CLI Run Command page for full documentation.

Port Configuration

The port can be configured in three ways (highest priority first):

CLI flag: aiderdesk start --port 8080
Environment variable: AIDER_DESK_PORT=8080 aiderdesk start
Default: 24337

Accessing the UI

Once the service is running, open your browser and navigate to:

http://localhost:<port>

The default address is http://localhost:24337.

From the browser, you get the full AiderDesk experience — project management, chat, context files, agent mode, and all other features work the same way as in the desktop app.

Requirements

Node.js 20 or later
Python 3.8+ (automatically managed via the bundled uv package manager)

Differences from the Desktop App

Feature	Desktop App	npm CLI
Electron window	✅	❌
Browser-based UI	✅ (via Docker)	✅
System tray integration	✅	❌
Native notifications	✅	❌
Auto-updates	✅	Update via `npm update -g @aiderdesk/aiderdesk`
Agent Mode	✅	✅
All AI features	✅	✅
REST API	✅	✅
MCP Server	✅	✅

Updating

To update to the latest version:

npm update -g @aiderdesk/aiderdesk

Next Steps

Open a project to start coding
Configure providers to connect your AI models
Explore Agent Mode for autonomous AI assistance

Installation​

Running​

Interactive TUI (Default)​

Headless Foreground​

Options​

Run a Prompt Non-Interactively​

Port Configuration​

Accessing the UI​

Requirements​

Differences from the Desktop App​

Updating​

Next Steps​