Getting Started

🚀 AionUi Quick Start Guide

Welcome to AionUi — the free, open-source Cowork app with AI Agents. This guide walks you through installation and first-run setup in about 5 minutes. AionUi ships with a complete AI agent engine built in, so it works the moment you install it — no CLI tools to install, no complex setup required.

English | 简体中文

📥 Step 1: Download and Install

System Requirements

• macOS: macOS 10.14 or higher
• Windows: Windows 10 or higher
• Linux: Ubuntu 18.04+ or other mainstream distributions
• Memory: At least 4GB RAM
• Storage: At least 500MB available space

Download Methods

Method 1: Homebrew Installation (Recommended for macOS)

brew install aionui

Method 2: Manual Download

1. Visit AionUi GitHub Releases
2. Choose the version suitable for your operating system:
   • macOS: Download .dmg file (Apple Silicon or Intel)
   • Windows: Download .exe installer
   • Linux: Download .deb or .AppImage file

Installation Steps

• macOS (Homebrew): Run brew install aionui to install automatically
• macOS (Manual): Double-click the .dmg file and drag AionUi to the Applications folder
• Windows: Run the .exe installer and follow the prompts
• Linux: Install the .deb file using package manager, or run the .AppImage directly

---

🎯 Step 2: First Launch

After installation, launch AionUi. You'll see the welcome screen on first startup:

The default experience uses AionUi's Built-in Agent — it's ready after you configure a model. If supported CLI agents are already installed (Claude Code, Codex, Qwen Code, etc.), AionUi detects them and brings them into the same Cowork interface. See the Multi-Agent Mode Setup guide for details.

---

⚙️ Step 3: Add a Model

AionUi's built-in Agent needs at least one model provider before you can chat. Add an API key in Settings → Models:

1. Click the Settings icon in the left sidebar
2. Open the Models page
3. Click Add Model and pick a provider — Gemini, OpenAI, Anthropic, ModelScope, OpenRouter, DeepSeek, and more are supported
4. Paste your API key and save

Multi-key rotation: You can paste multiple API keys (one per line). AionUi will auto-rotate them and skip invalid keys. See the LLM Configuration Guide for the full provider list and per-platform tips.

Already using a CLI agent? If Claude Code, Codex, Qwen Code, or another supported CLI is installed on your machine, AionUi connects to it automatically via ACP (Agent Client Protocol). Open the welcome page and pick the detected agent — no extra setup needed. See Multi-Agent Mode Setup for the supported list.

---

💬 Step 4: Start Your First Conversation

Create a New Conversation

1. Click the Chat icon in the left sidebar
2. Pick an agent — built-in Agent (default) or any detected CLI agent on the welcome page
3. Pick a model — use the model selector at the bottom-left of the input box (each agent has its own list of available models)
4. Type your message in the input box, then send

Try these prompts

Hello, please introduce yourself

Help me write a Python function to calculate the Fibonacci sequence

Please analyze the contents of this file

---

🔧 Step 5: Core Features

File Upload

• Drag & drop: drop files directly into the input box
• Pick from disk: click the + button in the input box to choose files or folders
• Supported: text files, images, code, PDFs, Office documents, and more

Multiple Conversations

• New conversation: click New Chat
• Switch: pick any conversation in the left history list — each conversation has independent memory

Project (Working Folder)

• Open a project: click the + button in the input box and select Open Folder
• Project panel: once opened, the Project panel appears on the right with the folder tree
• Quick file picking: browse and attach files to your message directly from the panel
• Locked per conversation: the project folder cannot be changed mid-conversation — start a new chat to use a different folder

---

❓ Common Questions

Q: I don't see any models after launch.

A: Open Settings → Models and add at least one provider's API key. Or, if you have a CLI agent installed (Claude Code, Codex, Qwen Code, etc.), AionUi auto-detects it on the welcome page.

Q: Image generation isn't working.

A: Check the following:

• Image generation is enabled in Settings → Tools
• A model that supports image generation is selected
• See the Image Generation Configuration Guide

Q: How do I switch between AI models?

A: Use the model selector at the bottom-left of the input box. Each agent (built-in, Claude Code, Codex, Qwen Code, etc.) exposes its own list of available models — switching the agent on the welcome page also switches the model list.

Q: Where are my conversations stored?

A: Everything is local:

• macOS: ~/Library/Application Support/AionUi/
• Windows: %APPDATA%/AionUi/
• Linux: ~/.config/AionUi/

---

🎉 You're Set!

You've finished AionUi's basic setup. You can now:

• ✅ Chat with the built-in Agent for daily AI tasks
• ✅ Upload files and folders for AI analysis and processing
• ✅ Generate and edit images
• ✅ Manage multiple parallel conversations

📚 Next Steps

• Provider details: LLM Configuration Guide
• Bring your CLI agents: Multi-Agent Mode Setup
• Real-world examples: Use Cases Overview
• Troubleshooting: FAQ

---

Need Help?

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Community Discussions

Let AI work alongside you — making every day easier and more efficient.