Installation

Desktop App (recommended)

The easiest way to run agtOS. The desktop app bundles everything — no Node.js, no terminal, no manual configuration. Download from GitHub Releases:

Platform	Format	Architecture
macOS	`.dmg`	Apple Silicon (arm64) + Intel (x86_64)
Windows	`.msi`	x86_64
Linux	`.AppImage`, `.deb`	x86_64

After installation, launch the app and follow the onboarding wizard. It guides you through API key setup, voice model downloads, and microphone configuration — all from a visual interface.

The desktop app includes a bundled Node.js backend compiled as a Single Executable Application. You don’t need to install Node.js, Redis, or any other dependency separately.

What’s included

System tray with health indicator (green/yellow/red)
Global push-to-talk hotkey (default: Alt+Space) — works from any application
Auto-start on system login (optional)
Auto-update from GitHub releases
Native notifications for health changes and task completions

See Desktop App for full details.

CLI (for developers)

For developers who want source access, customization, and terminal-based workflows.

Requirements

Component	Version	Required	What it enables
Node.js	22+	Yes	Core runtime
Docker	Latest	No	Convenient Redis management
Redis	7.2+ with RediSearch	No	Memory, scheduling, devices, preferences
Ollama	Latest	No	Local AI routing, embeddings, intent classification

Install methods

From source
Global CLI
Docker

git clone https://github.com/agtos-ai/agtos.git
cd agtos
npm install
npx agtos setup    # Interactive configuration wizard
npx agtos start    # Start the server

npm install -g agtos
agtos setup
agtos start

git clone https://github.com/agtos-ai/agtos.git
cd agtos
docker compose up -d

This starts agtOS, Redis, and speaches (STT/TTS fallback) together. See Docker Deployment for details including GPU acceleration.

Verify installation

npx agtos doctor

Runs 12 diagnostic checks (Node.js, Docker, Redis, Ollama, speech models, credentials, network, ports) and reports pass/warn/fail with remediation hints.

Ports

Port	Service	Protocol
3000	Voice pipeline	WebSocket (`/audio`), WebRTC signaling (`/webrtc`)
4100	MCP server	HTTP (`POST /mcp`)
4102	Health, REST API, dashboard, Prometheus metrics	HTTP

All configurable via VOICE_PORT, MCP_PORT, and HEALTH_PORT.

What’s next?

Quickstart

Step-by-step guide from install to first conversation.

Use Cases

See what you can build with agtOS.

Authentication

Set up Anthropic or OpenAI API keys.

FAQ

Common questions about setup, voice, and privacy.

​Desktop App (recommended)

​What’s included

​CLI (for developers)

​Requirements

​Install methods

​Verify installation

​Ports

​What’s next?

Quickstart

Use Cases

Authentication

FAQ

Desktop App (recommended)

What’s included

CLI (for developers)

Requirements

Install methods

Verify installation

Ports

What’s next?