[ Xoul ]

A personal assistant Agent for everyone.
With Local LLM and virtualization, your personal data can never be sent externally.
Streamline your daily life with Xoul.

🌐 한국어 | English

---

---

💡 Why Xoul

⚡ Practical AI Agent	Not a chatbot — it manages files, sends emails, browses the web, and runs code. 18 built‑in tools at OS level.
🔒 VM‑based Security	All actions run inside a QEMU virtual machine. Your host system stays untouched.
🔄 Daily Automation	Turn repetitive tasks (news digest, server checks, email triage) into scheduled workflows.
👥 Community‑driven	Import workflows, personas, and code snippets shared by others — or publish your own.

---

🚀 Features

• 📅 Personal Assistant — Calendar, email, and contacts management (Google integration)
• 🎭 Personas & Code — Switch agent roles or run Python snippets from the community hub
• 🔄 Workflows — Multi‑step automation templates with scheduling support
• ⚔️ AI Arena — Agent playground where AIs discuss topics and play social deduction games
• 🖥️ Host PC Control — Limited host interaction (browser launch, file operations)

---

🖥️ System Requirements

Component	Minimum	Recommended
CPU	x86‑64, 8 cores	—
RAM	8 GB	16 GB+
GPU	NVIDIA 30‑series, 8 GB VRAM	NVIDIA 40‑series, 16 GB+ VRAM
OS	Windows 11 (10 experimental)	—
Disk	20 GB free	—

---

📦 Installation

Prerequisites

The setup script installs everything automatically, but these are what it sets up:

• Python 3.12 — installed via winget if not found
• Ollama — local LLM inference engine
• QEMU — virtual machine for sandboxed agent execution

Quick Start (Recommended)

1. Visit the Xoul Download Page
2. Download the latest release zip and (optionally) the VM image
3. Run install.bat

install.bat automatically handles file placement and runs the setup script. The interactive setup will then walk you through each step:

Install from Source (Developers)

git clone https://github.com/xoul-project/xoul.git
cd xoul
.\scripts\setup_env.ps1

📋 Setup Steps Detail (Click to expand)

Step 1 — Language

Choose between Korean and English for all UI and messages.

Step 2 — LLM Model

Three options:

Mode	Description
Local (recommended)	Runs on your GPU via Ollama. Models auto‑download.
Commercial API	Claude, GPT‑5, Gemini, DeepSeek, Grok, Mistral — bring your API key.
External	Any OpenAI‑compatible endpoint (vLLM, LM Studio, etc.).

Local models are selected based on your VRAM:

Model	VRAM
Nemotron‑3‑Nano 4B (Q8)	~5 GB
Nemotron‑3‑Nano 4B (BF16)	~8 GB
GPT‑oss 20B	~13 GB
Nemotron‑Cascade‑2 30B	~20 GB

Additionally, BGE‑M3 (embedding) and Qwen 2.5 3B (summarization, CPU‑only) are installed automatically.

Step 3 — QEMU VM

QEMU is installed via winget. The setup tests WHPX hardware acceleration and creates or copies a VM image (~10 GB).

[!IMPORTANT] Enabling WHPX (Windows Hypervisor Platform) delivers 3–5× faster VM performance. We strongly recommend setting it up.

GUI setup:

1. Press Win + R → type optionalfeatures → Enter
2. Check ✅ Hyper-V and ✅ Windows Hypervisor Platform
3. Restart your PC

PowerShell setup (Run as Administrator):

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-All -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -NoRestart
Restart-Computer

[!TIP] After enabling, re-run setup_env.ps1 and WHPX acceleration will be automatically detected and applied.

Step 4 — Python Environment

A .venv is created with Python 3.12. All dependencies (openai, PyQt6, etc.) are installed from requirements.txt.

Step 5 — VM Image

If a pre‑built xoul.qcow2 is found, it's copied to the VM directory. Otherwise, a fresh image is created from a cloud image (~10–15 min).

Step 6 — Configuration

Interactive prompts for:

• User profile — name, location, agent name
• Email — Gmail with App Password (optional)
• ⚠️ Web Search — Tavily API key (recommended, free tier available). Search quality degrades significantly without it.
• Telegram / Discord / Slack — bot token setup (optional)
• GitHub — Personal Access Token for repo tools (optional)

Step 7 — Deploy & Launch

The agent code is deployed to the VM and all services start automatically. Once setup is complete, the Desktop App launches automatically.

---

🎯 Usage

To launch the Desktop App after setup:

c:\xoul\desktop\xoul.bat

Quick Bar

Press Ctrl+Space anywhere to open the Quick Bar — a floating input bar that lets you instantly type commands to your agent without switching windows.

Usage Example — Quick Bar + Application Launch

Use the Quick Bar to search and open a website directly in Chrome — no window switching needed.

"Search Youtube channel which is related to spring music and open it in chrome"

Usage Example — Workflow Execution

Workflows are multi-step automation templates that chain tools together — news digest, server health checks, email triage, and more. Trigger any workflow with a single command.

"Run morning briefing workflow"

Usage Example — Import from Xoul Hub

Browse and import community-shared workflows, personas, and code snippets from the Xoul Hub with a single click — instantly extend your agent's capabilities.

Usage Example — AI Arena

Join the AI Arena where multiple agents discuss topics and play social deduction games. Watch your agent interact autonomously with others in real time.

Usage Example — Telegram Integration

Chat with your agent through Telegram — manage tasks, run workflows, and get notifications on the go.

---

🧠 Supported Local Models

Models are automatically selected based on your available VRAM during setup.

#	Model	VRAM	Speed	Quality
1	Nemotron-3-Nano 4B (Q8)	7 GB	Fast	Low
2	Gemma 4 E2B ⚠️	8 GB	Fast	Mid
3	Nemotron-3-Nano 4B (BF16)	10 GB	Fast	Mid
4	Gemma 4 E4B ⚠️	10 GB	Fast	Mid
5	Qwen3-VL-8B-Instruct	14 GB	Fast	Mid
6	GPT-oss 20B	16 GB	Fast	Good
7	Gemma 4 26B ⚠️	18 GB	Mid	Good
8	Gemma 4 31B ⚠️	20 GB	Mid	Nice
9	Nemotron-Cascade-2 30B	24 GB	Little Slow	Nice

Note

⚠️ Gemma 4 series — Flash Attention with Gemma 4 on Ollama is not stable yet, so Flash Attention is currently disabled. This may result in slightly slower inference than expected.

Additionally, BGE-M3 (embedding) and Qwen 2.5 3B (summarization, CPU-only) are installed automatically.

---

📱 Clients

Client	Description
Desktop (PyQt6)	Native Windows app with chat UI
Telegram	Chat with your agent via Telegram bot
Discord	Mention your bot in any channel
Slack	Socket Mode integration
Terminal	CLI interface

---

📁 Project Structure

xoul/
├── server.py            # Main agent server
├── assistant_agent.py   # Agent logic & tool orchestration
├── llm_client.py        # LLM provider abstraction
├── vm_manager.py        # QEMU VM lifecycle
├── browser_daemon.py    # Headless Chromium controller
├── desktop/             # PyQt6 desktop client
├── tools/               # 18 built-in tools
├── scripts/             # Setup, deploy, launcher
├── locales/             # i18n (ko, en)
└── services/            # Systemd service files

---

🔧 Reconfiguration

If you need to re-run the setup, execute the following commands in order:

.\scripts\setup_env.ps1    # Re-run setup
.\scripts\launcher.ps1     # Start services

---

📄 License

MIT

---

🔗 Links

• 🌐 Website
• 💬 GitHub Discussions