Quickstart - agtOS

Get from zero to a working agtOS instance in about 5 minutes. Choose your path:

Desktop App (recommended)
CLI (developers)

The fastest way to get started. No terminal or Node.js required.

Download the app

Get the desktop app for your platform from GitHub Releases:

Platform	Download
macOS	`.dmg` (Apple Silicon + Intel)
Windows	`.msi` installer
Linux	`.AppImage` or `.deb`

Launch and onboard

Open the app. The onboarding wizard starts automatically and walks you through:

Dependencies — checks what’s available on your system
AI Provider — enter your Anthropic API key (and optionally an OpenAI key)
Speech Models — downloads voice models (~460MB) for local speech processing
Microphone Test — verifies your mic works with real-time audio levels
Preferences — choose your TTS voice, language, and push-to-talk hotkey

Don’t have a Claude API key? You can skip it and use local-only mode with Ollama. Or get a key from console.anthropic.com.

Start chatting

After onboarding, the dashboard opens with voice and text chat ready to use:

Voice — click the microphone or press your push-to-talk hotkey (default: Alt+Space) from any app
Text — type in the chat panel on the dashboard
System tray — agtOS runs in the background with a health indicator

The app also works as an MCP server — connect it to Claude Desktop for tool access.

For developers who want full control, source access, and terminal-based workflow.Prerequisites: Node.js 22+ (download)

Install

git clone https://github.com/agtos-ai/agtos.git
cd agtos
npm install

Run the setup wizard

npx agtos setup

The wizard checks dependencies, prompts for API keys, and validates them against the actual provider API.The wizard prompts for:

Anthropic API key — enter your sk-ant-api03-... key from console.anthropic.com, or press Enter to skip
OpenAI API key (optional) — enter your sk-... key from platform.openai.com, or press Enter to skip

You need at least one cloud provider key for chat and voice. Without any keys, agtOS runs in local-only mode with Ollama.

Download voice models (optional)

npx agtos models download --default

Downloads the default speech model set (~460MB) for local voice processing. Without models, agtOS runs in text-only mode.

Start the server

npx agtos start

  ✓ Health endpoint
  ✓ Voice pipeline
  ✓ MCP server
  ✓ Task scheduler
  ✓ API routes

agtOS server is running!
  Dashboard:  http://localhost:4102
  Voice WS:   ws://localhost:3000/audio
  MCP:        http://localhost:4100/mcp

Try it out

npx agtos chat

Or open the dashboard at http://localhost:4102, or connect from Claude Desktop:

{
  "mcpServers": {
    "agtos": { "url": "http://localhost:4100/mcp" }
  }
}

Optional: Start Redis for cross-session memory and task scheduling:

docker compose up -d redis

What’s next?

Use Cases

See what you can build with agtOS.

Explore Features

Voice pipeline, memory, MCP tools, dashboard, and more.

Configuration Guide

Configure providers, models, and advanced options.

FAQ

Common questions about setup, voice, memory, and privacy.

Documentation Index

​What’s next?

Use Cases

Explore Features

Configuration Guide

FAQ

What’s next?