ContextuAI Solo User Guide

Installation

Download the installer for your platform and run it — no build tools, no terminal commands, no dependencies to install.

Step 1: Download

Go to the GitHub Releases page and download the latest version for your OS:

Step 2: Launch

Open ContextuAI Solo from your applications. On first launch, the Setup Wizard guides you through choosing an AI provider and configuring your profile. That's it — you're ready to go.

Building from Source (Advanced)

If you prefer to build from source (contributors, developers):

Setup Wizard

On first launch, a 3-step wizard walks you through configuration:

1. Profile — Enter your name, business name, and select your industry (16 options: SaaS, E-commerce, Healthcare, Finance, Education, Marketing, Consulting, Real Estate, Legal, Manufacturing, Non-Profit, Freelancing, and more)
2. AI Provider — Choose how you want to run AI:

   Built-in Local AI Free · No Setup

   Solo ships with a built-in Model Hub — 41 prebuilt GGUF models ready to download, plus access to 140,000+ GGUF models on Hugging Face. No API keys, no external tools, no Ollama, no Python — just pick a model, click download, and start chatting. Everything runs on your CPU, fully offline.

   This is the fastest way to get started. The wizard lets you pick a recommended model based on your RAM:

   Your RAM	Recommended Model	Download Size
   4-8 GB	Qwen 3.5 0.8B or Gemma 3 1B	~700 MB
   8-16 GB	Qwen 3 8B or DeepSeek R1 7B	~4-5 GB
   16-32 GB	Gemma 4 12B or Qwen 3 14B	~7-9 GB
   32+ GB	Gemma 4 27B or DeepSeek R1 32B	~16-20 GB

   New: Gemma 4 — Google's latest model family (April 2025). Gemma 4 12B rivals models twice its size on reasoning and instruction-following. Gemma 4 27B is one of the strongest open models available. Both run fully on CPU inside Solo — our top recommendation for 16GB+ machines.

   Cloud Providers BYOK

   If you have API keys from cloud providers, you can add them for access to the latest frontier models:

   • Anthropic Claude — Sonnet 4, Opus, Haiku (Get API key)
   • OpenAI — GPT-4o, GPT-4o Mini, GPT-4 Turbo, o1-preview (Get API key)
   • Google Gemini — 2.0 Flash, 2.0 Pro, 1.5 Flash (Get API key)
   • AWS Bedrock — Claude and Titan models
   • Ollama — If you already run Ollama locally, Solo can connect to it as an additional provider

   You can use local + cloud together — switch between them anytime from the model dropdown in chat.

3. Brand Voice — Define your target audience, content topics, and brand tone

Your First Chat

After the wizard, you land on the Chat page:

1. Type a message in the input box at the bottom
2. Select an AI model from the dropdown (shows provider badges: Local/Cloud)
3. Optionally pick a persona to give the AI specialized context
4. Press Enter to send — the AI streams its response in real-time

Conversations are saved as sessions in the left sidebar, grouped by date with message counts.

The main chat interface with model selector, persona picker, and session sidebar

AI Chat

The chat interface is the heart of Solo:

• Multi-model support — Switch between providers and models mid-conversation using the dropdown
• Real-time streaming — Responses appear token-by-token; click the stop button to abort
• Session management — Create, rename, archive, delete, and search sessions from the sidebar
• Persona selection — Attach a persona to give the AI access to your database, API, or custom instructions
• Markdown rendering — Code blocks with syntax highlighting, tables, lists, and rich formatting
• Thinking mode — Models that support reasoning (Qwen 3, DeepSeek R1) show a collapsible thinking section
• Dark/Light mode — Toggle from the top bar; applies across all pages

Model Hub

Configure cloud AI providers and download local models from Settings → AI Providers.

Browse and configure AI models — cloud providers and local GGUF models

Cloud Providers

Enter your API key for any supported provider. Click Test Connection to verify it works. Toggle the active provider to set your default model.

Local Models

Download GGUF models with one click. Solo auto-detects your RAM and recommends compatible models. Progress is shown in real-time during download.

Manage installed local models — sync status, storage usage, ready to chat

AI Mode Toggle

Switch between Local and Cloud mode. In local mode, all inference runs on your CPU — no internet required after model download.

Personas

Personas are AI identities that connect to your real systems. Solo includes 12 persona types:

Agent library showing all agent types and kinds

Creating a Persona

Solo uses a 2-step wizard:

1. Choose Type — Select from the persona type dropdown (each type shows an icon and description)
2. Configure Details — Enter name, category, description, connection credentials, and system prompt

For database types, use the Test Connection button to verify credentials before saving.

Create agent — select type, configure settings, and customize

Agent Library

Solo ships with 96 prebuilt business agents across 14 departments, plus you can create unlimited custom agents. Each has a specialized system prompt, recommended model, and tool configurations.

Browse 96 prebuilt agents across 14 departments — search, filter by role, view details

Agents organized by kind — Prompt, Database, Web, MCP, API, and File

Using Agents

Browse by department or filter by role: Researcher, Writer, Analyst, Designer, Developer, Reviewer, Planner, or Custom. Click any agent card to view its full system prompt, tools, and model override.

Creating a Custom Agent

Click + Create Agent and configure: name, role, description, system prompt, tool access, model preference, category, and public/private visibility.

Create a custom agent with role, system prompt, and tool configuration

Crews

Crews are multi-agent teams that collaborate on complex tasks. The crew system uses a 7-step creation wizard.

Crew dashboard with stats (Total, Running, Completed, Failed) and crew list

Crew Builder Step 2 — choose execution mode: Sequential, Parallel, Pipeline, or Autonomous

Crew Builder Step 3 — add agents from the library, organized by kind

7-Step Crew Wizard

Running a Crew

Click Run on any crew. Enter your input text and watch real-time progress: status bar, duration, token count, cost, step timeline, and per-agent metrics. You can cancel a run mid-execution.

The Runs tab shows execution history with status, duration, and cost for every past run.

Blueprints

Solo ships with 10 pre-built crew templates across 5 categories to jumpstart your workflows.

Browse blueprint templates — search, filter by category, preview content

10 Blueprints

Reusable crew configurations across 5 categories (Strategy, Content, Marketing, Product, Research):

• Strategy — OKR Planning, SWOT Analysis, Lean Canvas Brainstorm
• Content — Blog Content Pipeline, Social Media Strategy
• Marketing — Campaign Planning
• Product — Feature Prioritization, User Story Workshop
• Research — Competitor Analysis

Each blueprint pre-selects agents, execution mode, and goals. Clone and customize to fit your specific workflow.

Creating Custom Blueprints

Click + Create Blueprint and define: name, description, category, tags, and markdown content. Your custom blueprints appear alongside the built-in ones.

Create a custom blueprint with markdown content and tags

Knowledge Base

Solo includes a fully local RAG (Retrieval-Augmented Generation) system. Upload documents or map folders from your machine — Solo chunks, embeds, and indexes everything locally. Ask questions in chat and get answers with source citations.

Adding Documents

Two ways to add content to a Knowledge Base:

• File Upload — Drag and drop PDF, DOCX, TXT, or Markdown files (up to 10 MB each)
• Folder Mapping — Point at any directory on your machine (Obsidian vault, Notes folder, code repo). Solo indexes all supported files recursively up to depth 10.

How Indexing Works

Folder Mapping Schedules

Auto-sync options: Manual, Every 1 hour, Every 6 hours, or Every 24 hours. Solo tracks file changes (new, modified, deleted) using path + size + modification time. A friction guardrail pauses indexing if a folder contains more than 1,000 files — you confirm before proceeding.

Using a Knowledge Base in Chat

1. Select a KB from the dropdown above the chat input
2. Ask your question — Solo retrieves relevant chunks and passes them to the AI model
3. The AI responds with [1], [2] citations pointing back to source documents

Limits

• Max file size: 10 MB per file
• Max files per folder mapping: 5,000
• Max folder depth: 10 levels
• Works with both local GGUF models and cloud providers

Automations

Automations are quick, one-off agent tasks using natural-language @mention syntax. No wizard needed — just type and run.

Automation list with @agent-mention prompts, triggers, and output actions

How It Works

1. Write a prompt with @agent-handle mentions (e.g., @content-strategist write a LinkedIn post about our Q2 launch)
2. Solo's parser detects the agents and infers the execution mode (sequential if ordered, parallel if independent)
3. Agents execute and stream results in real-time

Output Options

Promote to Crew

Any automation can be promoted to a scheduled crew with one click. The agent selections, output action, and context carry over — just add triggers and approval settings.

Automation builder — name, @agent prompt, trigger configuration, and output action picker

Connections

Connect Solo to external messaging platforms for automated content publishing and AI-powered responses.

Platform connection cards with status badges and direction toggles

Setting Up Telegram

1. Open Telegram, search for @BotFather
2. Send /newbot and follow the prompts to get your bot token
3. In Solo, go to Connections → Telegram → paste the token
4. Toggle Inbound/Outbound as needed and click Connect
5. For inbound messages, set up a webhook with ngrok: ngrok http 18741

Setting Up Discord

1. Go to the Discord Developer Portal
2. Create a New Application → go to Bot → copy the token
3. Enable Privileged Gateway Intents (Message Content, Server Members)
4. In Solo, paste the Bot Token, Public Key, and Application ID

Setting Up LinkedIn

1. Create an app at LinkedIn Developers
2. Request "Share on LinkedIn" access for your app
3. In Solo, enter Client ID and Client Secret
4. Click Connect — an OAuth browser window will open for authorization

Connected platforms can be bound to crews in Step 4 of the crew wizard, enabling automated content distribution with human-in-the-loop approval.

Approval Queue

When crews or agents auto-reply to incoming messages, every response lands in your approval queue first. Nothing gets sent without your explicit approval.

Review AI-drafted replies before they are sent — approve, edit, or reject

1. Set up triggers — Link a channel (Telegram, Discord) to a crew or agent with "require approval" enabled
2. AI drafts a reply — Incoming messages are processed by your AI; the draft appears in the queue
3. Review & send — Edit the response if needed, then approve to send or reject to discard

Triggers support cooldown periods to prevent spam, and you can link a crew instead of a single agent for more sophisticated multi-step responses.

Coder Mode

Toggle into Coder Mode (Ctrl+Shift+M / Cmd+Shift+M) for a local development workspace with AI-powered multi-agent coding workflows.

Mode Toggle

A pill toggle at the top center of the app switches between Solo (business assistant) and Coder (development workspace). Your mode preference is saved and persists across sessions.

Coder Sidebar

• Projects — Create, list, and run coding projects
• Running — Active executions with stdout streaming and kill button
• Templates — 4 starter scaffolds (Web App, Telegram Bot, CLI Tool, Static Site)
• Models — Model selector for coding tasks
• Settings — Provider keys and coder-specific configuration

Project Templates

Multi-Agent Workflows

Define agent roles (planner, coder, reviewer) and run them in 4 workflow modes:

5 Coder-Companion Agents

Visible only in Coder Mode:

• Code Reviewer — PR review, quality feedback
• Bug Analyzer — Error diagnosis, stack trace interpretation
• Test Writer — Unit test and integration test generation
• Doc Generator — Docstring and README generation
• Refactor Advisor — Code cleanup, performance optimization

Sandboxed Shell

Run dev servers, build commands, and tests in a restricted shell. Tauri capabilities restrict file system access to the project directory only. Each project has a trust state that controls what commands can execute.

Cross-Mode Handoffs

Crews can include a "Run Coder Project" step to execute a coding project headlessly. Automations can also invoke Coder workflows. This lets you chain business logic (Solo) with coding tasks (Coder) in a single pipeline.

Index Codebase as Knowledge Base

Coder projects can be indexed as a Knowledge Base (folder-mapped RAG), making the entire codebase searchable by AI agents during code review or bug analysis.

BYOK — Bring Your Own Key

Solo supports 5 AI providers. Configure in Settings → AI Providers:

API keys are stored in your browser's localStorage. They are never sent to any server other than the respective AI provider.

Local Models

Solo includes a Model Hub with 41 prebuilt GGUF models across 9 families, plus access to 140,000+ GGUF models on Hugging Face. One-click download — no API key, no internet after download, no data leaving your machine.

RAM Requirements

9 Model Families (41 Models)

• Gemma 4 New · Recommended — Google's latest (April 2025). 12B and 27B variants. Best-in-class instruction following, reasoning, and multilingual support at its size. Our top pick for 16GB+ machines.
• Qwen 3.5 / 3 / 2.5 — Alibaba's versatile family. General chat, reasoning, and coding (Qwen 2.5 Coder is excellent for IDE integration). Wide range from 0.8B to 32B.
• DeepSeek R1 — Advanced reasoning with visible thinking mode. 7B to 70B. Great for analysis, math, and complex problem-solving.
• Gemma 3 — Google's previous generation. Still solid for lightweight tasks (1B to 27B).
• Llama 3 — Meta's open models. 1B to 70B. Strong general-purpose performance.
• Mistral — Fast and lightweight (7B). Good for quick responses on lower-spec machines.
• Phi-4 — Microsoft's 14B model. Punches above its weight on reasoning tasks.

Inference powered by llama-cpp-python — CPU-only, no GPU required. Models stored in ~/.contextuai-solo/models/.

Built-in Coding Server

Solo exposes an OpenAI-compatible API at localhost:18741/v1/chat/completions. Point your IDE at it for free, offline code completion.

IDE Setup

Settings

Access settings from the sidebar. 5 tabs:

Settings page with AI Providers, Brand Voice, Appearance, Data & Export, and About tabs

AI Providers tab — configure cloud provider API keys (Anthropic, OpenAI, Google, Bedrock, Ollama)

• AI Providers — Configure API keys, download local models, test connections, set active provider
• Brand Voice — Business name, industry, brand prompt, target audience, content topics
• Appearance — Theme (Light, Dark, System) and font size (Small, Medium, Large)
• Data & Export — Export/import database as JSON, clear all data
• About — App version, check for updates, technology stack links

Brand Voice

Configure your brand identity so AI-generated content matches your tone. Settings → Brand Voice:

• Business Name — Used in agent prompts and content generation
• Industry — 12 options (Tech, Marketing, Finance, Healthcare, etc.) to inform domain knowledge
• Brand Voice Prompt — Free-form instructions: tone, style, personality, things to avoid
• Target Audience — Who your content is aimed at
• Content Topics — Key subjects the AI should focus on

A dynamic preview shows how your brand voice configuration looks before saving.

Data & Export

All your data lives locally. From Settings → Data & Export:

• Export Data — Download a full JSON backup of all chats, personas, agents, crews, and settings
• Import Data — Restore from a previous backup file
• Clear All Data — Permanently delete everything (use with caution)

Keyboard Shortcuts

Data Storage

Everything is stored locally on your machine:

No telemetry, no cloud calls (except to your chosen AI provider), no data collection.

Tech Stack

Troubleshooting

Backend won't start

• Verify Python 3.11+: python --version
• Install dependencies: cd backend && pip install -r requirements.txt
• Check port 18741 is free: netstat -ano | findstr 18741 (Windows) or lsof -i :18741 (Mac/Linux)

Frontend won't start

• Verify Node.js 18+: node --version
• Clean install: rm -rf node_modules && npm install
• Windows rollup error: npm install @rollup/rollup-win32-x64-msvc

Chat returns errors

• Verify API key in Settings → AI Providers → Test Connection
• If using Ollama, make sure it's running: ollama serve
• Check the backend terminal for error details

Local model download fails

• Check internet connection (download only — inference is fully offline)
• Ensure enough disk space in ~/.contextuai-solo/models/
• Try a smaller model first (Gemma 3 1B is ~700MB)

Telegram/Discord webhook not receiving messages

• Ensure ngrok is running: ngrok http 18741
• Set the webhook URL in the platform's settings to your ngrok HTTPS URL
• Check Discord privileged intents are enabled (Message Content, Server Members)

Database reset

• Export your data first from Settings → Data & Export
• Delete ~/.contextuai-solo/data/contextuai.db
• Restart the backend — it recreates the database with defaults