Getting Started with Qualixar OS

April 13, 2026 ยท View on GitHub

Qualixar OS is the Universal OS for AI Agents. One control plane to orchestrate LLM agents across 15+ providers, 13 topologies, and every major IDE and framework.

Quick Start

Three commands. Zero cost. Ollama runs locally on your machine.

# 1. Install Qualixar OS
npm install -g qualixar-os

# 2. Pull a free local model
ollama pull llama3.3

# 3. Launch the dashboard
qos dashboard

Open http://localhost:3000. You now have a full agent operating system running locally.

Note: The default server port is 3000. Both qos serve and qos dashboard accept --port to override it.

Submit Your First Task

From the Dashboard: Go to the Chat tab, select llama3.3 from the model dropdown, type a prompt, and press Enter.

From the CLI:

qos run "Summarize the benefits of multi-agent systems in 3 bullet points"
qos status <task-id>    # Check task progress
qos output <task-id>    # View completed output

Prerequisites

  • Node.js 22+ (required for ESM top-level await; 22 LTS or later recommended)
  • Ollama for local models, or an API key for any cloud provider

Alternative Install

Run without a global install:

npx qualixar-os dashboard

Verify your installation:

qos --version
qos doctor

Choose Your Provider

Qualixar OS connects to 15+ LLM providers through a single interface. Start with Ollama (free, local), then add cloud providers as needed.

ProviderModelsCostSetup
OllamaLlama 3.3, Mistral, Gemma, Phi, 100+FreeLocal install
OpenRouter100+ models from every vendorPay-per-tokenAPI key
Ollama Cloud36+ hosted modelsFree tier availableAPI key
OpenAIGPT-4o, GPT-5, o3Pay-per-tokenAPI key
AnthropicClaude Opus, Sonnet, HaikuPay-per-tokenAPI key
AzureOpenAI models via AzureEnterprise billingEndpoint + key
LM StudioAny GGUF modelFreeLocal install
CustomAny OpenAI-compatible APIVariesBase URL + key

Add providers from the dashboard (Settings > Providers) or via qos init.

Full provider documentation: providers/overview.md

Core Concepts

The Pipeline

Every task in Qualixar OS flows through a five-stage pipeline:

Memory --> Forge --> Agents --> Judge --> Output
  1. Memory retrieves relevant context from past tasks and external knowledge
  2. Forge AI automatically designs the optimal agent team for the task
  3. Agents execute the work across one of 13 topologies
  4. Judge Pipeline evaluates output quality against configurable criteria
  5. Output delivers the verified result

Forge AI (Auto Team Design)

Forge analyzes your prompt and assembles the right agents, tools, and topology automatically. No manual configuration required for most tasks. You can override any decision.

Documentation: dashboard/forge.md

Judge Pipeline (Quality Assurance)

Every task output passes through judges that score correctness, completeness, and safety. Configure judge thresholds, add custom judges, or bypass for speed.

Documentation: dashboard/judges.md

13 Topologies

Qualixar OS supports 13 execution topologies, from simple single-agent to complex multi-agent orchestrations:

TopologyCode NameUse Case
SequentialsequentialStep-by-step chain of agents
ParallelparallelIndependent agents, merged results
HierarchicalhierarchicalManager delegates to workers
DAGdagDirected acyclic graph with complex dependencies
Mixture of Agentsmixture_of_agentsEnsemble answers, synthesized output
DebatedebateAgents argue, judge picks winner
MeshmeshAll-to-all collaboration
StarstarHub coordinates spokes
CircularcircularRound-robin iterative refinement
GridgridMatrix neighbor communication
ForestforestMultiple parallel hierarchies
MakermakerBuild-test-ship engineering loop
HybridhybridLocal/cloud PII-safe split

Documentation: reference/topologies.md

Memory System

Qualixar OS persists task history, agent decisions, and retrieved context across sessions. Integrates with SuperLocalMemory for cross-tool knowledge sharing.

Documentation: memory/overview.md

Documentation Index

Dashboard (24 Tabs)

The web dashboard provides full visual control over every aspect of agent orchestration. Default port: 3000 (configurable via --port).

TabDescriptionDocs
OverviewDashboard home, system statusdashboard/overview.md
ChatInteractive model chatdashboard/chat.md
AgentsAgent configuration and managementdashboard/agents.md
SwarmsMulti-agent swarm orchestrationdashboard/swarms.md
ForgeAI-powered team designdashboard/forge.md
JudgesQuality assurance pipelinedashboard/judges.md
PipelinesTask pipeline builderdashboard/pipelines.md
FlowsVisual workflow editordashboard/flows.md
MemoryMemory browser and searchdashboard/memory.md
VectorsVector store managementdashboard/vectors.md
BrainKnowledge graph visualizationdashboard/brain.md
ToolsTool registry and configurationdashboard/tools.md
BlueprintsReusable task templatesdashboard/blueprints.md
BuilderVisual agent builderdashboard/builder.md
LabExperimentation sandboxdashboard/lab.md
DatasetsDataset management for evaluationdashboard/datasets.md
MarketplaceSkill and plugin marketplacedashboard/marketplace.md
ConnectorsExternal service integrationsdashboard/connectors.md
GateAccess control and permissionsdashboard/gate.md
AuditAudit log and compliancedashboard/audit.md
CostToken usage and cost trackingdashboard/cost.md
LogsSystem and task logsdashboard/logs.md
TracesExecution trace viewerdashboard/traces.md
SettingsProvider config, preferencesdashboard/settings.md

CLI (25 Commands)

Full command-line interface for headless and scripted workflows.

CommandWhat It Does
qos initInteractive setup wizard
qos serveStart HTTP/WebSocket server
qos dashboardStart standalone dashboard (default port 3000, configurable via --port)
qos run <prompt>Run a task
qos status <id>Check task status
qos output <id>View task output
qos modelsList available models
qos doctorHealth check
qos config <key> <val>Update configuration

Full CLI reference: cli/overview.md | CLI vs MCP comparison: cli/cli-vs-mcp.md

Protocols

ProtocolDescriptionDocs
MCPModel Context Protocol server/clientprotocols/mcp.md
A2AAgent-to-Agent protocol supportprotocols/a2a.md
OverviewProtocol architectureprotocols/overview.md

Frameworks

Integrate Qualixar OS as a backend for popular agent frameworks.

FrameworkDocs
LangChainframeworks/langchain.md
CrewAIframeworks/crewai.md
AutoGenframeworks/autogen.md
OpenAI Agentsframeworks/openai-agents.md
Semantic Kernelframeworks/semantic-kernel.md
Customframeworks/custom-integration.md
Overviewframeworks/overview.md

Claude CLI Integration

Use Qualixar OS directly from Claude Code or any Claude CLI session.

TopicDocs
Overviewclaude-cli/overview.md
MCP Setupclaude-cli/mcp-setup.md
Plugin Installclaude-cli/plugin-install.md
Skills Guideclaude-cli/skills-guide.md
CLI Native Bridgeclaude-cli/cli-native-bridge.md
Power Userclaude-cli/power-user.md

IDE Integration

TopicDocs
Overviewide-integration/overview.md
MCP Protocolide-integration/mcp-protocol.md

Providers

ProviderDocs
Overviewproviders/overview.md
Ollamaproviders/ollama.md
OpenRouterproviders/openrouter.md
Ollama Cloudproviders/ollama-cloud.md
OpenAIproviders/openai.md
Anthropicproviders/anthropic.md
Azureproviders/azure.md
LM Studioproviders/lmstudio.md
Customproviders/custom.md

Memory

TopicDocs
Overviewmemory/overview.md
SuperLocalMemorymemory/superlocalmemory.md
SLM Integrationmemory/slm-integration.md

Guides

GuideDescriptionDocs
Quickstart (5 Minutes)Install, launch dashboard, run your first agent teamguides/quickstart-5-minutes.md
Multi-Agent Code ReviewCode review with debate topology and judge verdictsguides/multi-agent-code-review.md
MCP Server SetupUse QOS from Claude Code, VS Code, or Cursor via MCPguides/mcp-server-setup.md
First Multi-Agent TaskRun agents in parallel, pipeline, or debateguides/first-multi-agent-task.md
MCP IntegrationConnect external MCP servers to Qualixar OSguides/mcp-integration.md
Deploy with DockerContainerized deploymentguides/deploy-docker.md
Security SetupAuth, TLS, and access controlguides/security-setup.md
Cost OptimizationReduce token spend across providersguides/cost-optimization.md
TroubleshootingCommon issues and fixesguides/troubleshooting.md

Reference

ReferenceDescriptionDocs
API EndpointsAll 27+ REST endpointsreference/api-endpoints.md
Config SchemaFull config.yaml specificationreference/config-schema.md
Topologies13 execution topologiesreference/topologies.md
EventsEvent system and hooksreference/events.md
Skill ManifestSkill package formatreference/skill-manifest.md
Tool CategoriesTool classification systemreference/tool-categories.md

Key Paths

ItemLocation
Config~/.qualixar-os/config.yaml
Environment~/.qualixar-os/.env
Database~/.qualixar-os/qos.db
Logs~/.qualixar-os/logs/
Plugins~/.qualixar-os/plugins/

Next Steps

Once you have the dashboard running and your first task complete, here is where to go next:

  1. Try different topologies. Run the same task as a debate, pipeline, or parallel execution. See how agent collaboration changes the output. Start with the First Multi-Agent Task guide.

  2. Install marketplace skills. Open the Marketplace tab in the dashboard and install pre-built skills for coding, research, writing, and more. See dashboard/marketplace.md.

  3. Connect from Claude Code. Add Qualixar OS as an MCP server in your Claude CLI config and orchestrate agents without leaving your terminal. See claude-cli/mcp-setup.md.

  4. Connect from VS Code. Use the IDE integration to run agent tasks directly from your editor. See ide-integration/overview.md.

  5. Add a cloud provider. Pair Ollama with a cloud model for hybrid local+cloud topologies. Open Settings > Providers or see providers/overview.md.

  6. Deploy with Docker. Run Qualixar OS as a persistent service. See guides/deploy-docker.md.

  7. Read the paper. The research behind Qualixar OS is published on arXiv: 2604.06392.