Orkas Documentation Orkas 文档 Orkas ドキュメント
Everything you need to install Orkas, connect your own model, and direct an AI team — plus how the local-first, multi-agent architecture works under the hood. 安装 Orkas、接入你自己的模型、指挥一支 AI 团队所需的一切 —— 以及本地优先的多 agent 架构在底层是如何运作的。 Orkas のインストール、自分のモデルの接続、AI チームの指揮に必要なすべて。そして、ローカルファーストなマルチエージェント・アーキテクチャが内部でどう動くかを解説します。
# Introduction
Orkas is an open-source, local-first desktop AI client. Instead of chatting with a single assistant, you direct a team: a lead agent owns your goal and recruits sub-agents, each of which calls skills to get work done. You describe the goal in chat instead of drawing a flowchart or setting up automation rules.
It runs on macOS and Windows. Your model keys stay on your machine, and your workspace is local-first by default; you bring your own LLM provider keys.
# Install
Download the desktop client and open it — no account required to start.
Download
Get the build for your OS from the download page or GitHub releases.
Open
Launch Orkas. On first run it sets up a local data directory on your machine.
Stay current
The app checks for updates; the open-source build can also be pulled and run from source.
# run from source (open-source build)
git clone https://github.com/Orkas-AI/Orkas
cd Orkas/PC && ./run.sh# Connect a model
Orkas is bring-your-own-model. Open Settings → Models and add a provider via OAuth or an API key. Traffic goes directly from your machine to the provider — it is never proxied through Orkas servers.
| Provider | How you connect | Where your data goes |
|---|---|---|
| OpenAI (GPT) | OAuth or API key | Direct to provider · never proxied |
| Anthropic (Claude) | OAuth or API key | Direct to provider · never proxied |
| Google (Gemini) | OAuth or API key | Direct to provider · never proxied |
| MiniMax | API key | Direct to provider · never proxied |
| Kimi (Moonshot) | API key | Direct to provider · never proxied |
| Zhipu (GLM) | API key | Direct to provider · never proxied |
| + more, added over time | OAuth or API key | 100% local — keys on your device |
# Your first task
Type a goal in the Commander chat. The lead agent plans, recruits the sub-agents it needs, and streams results back. Risky steps pause for your approval.
you › turn this product idea into a launch checklist and a first-week plan
› lead agent recruiting: planner, writer
planner › breaks work into milestones and owners
writer › drafts announcement copy and open questions
✓ plan ready — review it in chat# Architecture
One task flows through three layers. Each actor has a clear responsibility and a bounded context, so a single request can span disciplines without overflowing one context window.
Direct
State a goal in natural language.
Orchestrate
Owns the full context; recruits sub-agents and splits the work.
Execute
Each works in its own context, calling skills to deliver.
# Lead & sub-agents
The lead agent (Commander) holds the global thread and decides who does what. Sub-agents are specialists you can also summon directly with @name. Turn a recurring task into a sub-agent once, then summon it forever — that's "sub-agents as workflows".
- Auto-assembly — the lead picks sub-agents by task and capability.
- Context boundaries — sub-agents see only what the lead passes plus your direct messages.
- Self-evolution — via meta-cognition, agents review their runs and improve next time (on by default).
# External agents
Already living in a coding CLI? Orkas can drive external CLI coding agents as local subprocesses and manage them alongside its own native team — so you summon them in chat like any other agent and direct everything from one interface.
| CLI | Notes |
|---|---|
| Claude Code | Anthropic's coding CLI. |
| Codex | OpenAI's coding CLI. |
| OpenClaw | Open-source coding CLI. |
| Hermes | Coding CLI. |
| OpenCode | Open-source coding CLI. |
- Install it yourself — you install the CLI; Orkas does not bundle or install it for you.
- Auto-detect — Orkas scans your PATH for the binary (or a custom path you set via
ORKAS_<TYPE>_PATH), runs--version, and checks a minimum version. - Attach & run — pick a detected CLI as an agent's runtime; Orkas spawns it as a local subprocess inside your conversation, managed next to native agents.
# Skills
Skills are an agent's arms — capabilities like web search, code execution, file I/O, image generation, and connector calls. Use the built-ins, write your own, or install from the Marketplace.
| Skill | What it does |
|---|---|
| web_search | Query the web through a search provider, return structured results. |
| code_exec | Run shell / code in a sandbox to reproduce, build, or test. |
| file_io | Read and write files in the working directory. |
| kb_search | Semantic + keyword search over your local knowledge base. |
| create_artifact | Generate a self-contained interactive app, run it sandboxed. |
# Knowledge base
Drop PDFs, markdown, and docs into a local knowledge base. Files are chunked and indexed on your machine; agents kb_search them to answer with citations. The source files stay local — only your model call leaves the device.
# Memory
Orkas keeps personal memory across sessions in two local files: preferences (who you are, how you like things) and facts (decisions, project context). Both are editable, importable, and injected at session start so the team compounds knowledge about how you work.
# Tech stack
Orkas is an Electron desktop app. The lead and sub-agent runtime runs inside the app, and your LLM calls go straight from your machine to your provider — no Orkas server runs your agents.
| Layer | Built with |
|---|---|
| Desktop shell | Electron — macOS / Windows from one codebase. |
| Backend | TypeScript agent runtime in the app; can also drive local CLI coding agents (Codex, Claude Code, …) as subprocesses. |
| Renderer | Vanilla HTML / CSS / JS via a sandboxed bridge — no framework lock-in. |
| Storage | Local JSON / JSONL files; in-memory hybrid (vector + keyword) search for the knowledge base. |
| Models | BYO LLM keys via OAuth or API key; called directly, never proxied. |
# Data & privacy
Orkas is local-first: by default your agent configs, chats, knowledge bases, files, and memory live on your machine, and your encrypted keys and model traffic never go through Orkas. Lite's optional multi-device sync stores synced data on Orkas servers; the free edition sends limited usage analytics. Full details on the Security & Trust page.