Orkas Documentation Orkas 文档 Orkas ドキュメント Documentação do Orkas
Everything you need to install Orkas, choose a managed official model or connect your own provider, and direct an AI team — plus how the local-first, multi-agent architecture works under the hood. 安装 Orkas、选择托管官方模型或接入自有服务商、指挥一支 AI 团队所需的一切 —— 以及本地优先的多 agent 架构在底层是如何运作的。 Orkas のインストール、公式マネージドモデルの選択または自分のプロバイダーの接続、AI チームの指揮に必要なすべて。そして、ローカルファーストなマルチエージェント・アーキテクチャが内部でどう動くかを解説します。 Tudo de que você precisa para instalar o Orkas, escolher um modelo oficial gerenciado ou conectar seu próprio provedor e dirigir uma equipe de IA — além de entender a arquitetura local-first e multiagente.
# 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, and your workspace is local-first by default. Choose an Orkas-managed official model, or connect your own provider; provider keys stay on your machine.
# 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 provides official models you can use directly, and it is also bring-your-own-model. Open Settings → Models to add a provider via OAuth or an API key. With your own keys, traffic goes directly from your machine to the provider — not proxied through Orkas; official models run through Orkas's managed model service.
| Provider | How you connect | Where your data goes |
|---|---|---|
| Orkas official models | Available in Orkas | Orkas-managed model service |
| 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 |
| DeepSeek | 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 Commander. Local tools follow your permission mode: approval modes prompt for sensitive operations, while routine operations may run without prompting.
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. Source files and the index stay local; the selected model service receives the excerpts needed to answer.
# 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, and the lead and sub-agent runtimes stay inside it. Official models use Orkas's managed service; own-provider calls go direct. Orkas servers do not run your agent team.
| 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 | Orkas-managed official models, or your provider through OAuth or an API key; own-provider calls go direct. |
# FAQFAQ常见问题よくある質問
Is Orkas free and open source?O Orkas é gratuito e open source?Orkas 免费且开源吗？Orkas は無料でオープンソースですか？
Yes. The Orkas desktop client is open source and free to download. Optional managed official models and other metered managed features consume Orkas credits; if you connect your own provider, that provider bills its usage directly.Sim. O cliente desktop Orkas é open source e gratuito para baixar. Modelos oficiais gerenciados e outros recursos medidos consomem créditos Orkas; ao conectar seu próprio provedor, ele cobra o uso diretamente.是的。Orkas 桌面客户端开源且可免费下载。可选托管官方模型和其他按量托管能力消耗 Orkas 积分；接入自己的供应商时，由该供应商直接计费。はい。Orkas デスクトップクライアントはオープンソースで無料ダウンロードできます。任意の公式マネージドモデルなどの従量機能は Orkas クレジットを消費し、自分のプロバイダーを接続した場合はそのプロバイダーが直接課金します。
Which AI models can I use with Orkas?Quais modelos de IA posso usar com Orkas?Orkas 能用哪些 AI 模型？Orkas ではどの AI モデルを使えますか？
Orkas provides official models you can use directly, and it is also bring-your-own-model. You connect providers such as OpenAI (GPT), Anthropic (Claude), Google (Gemini), DeepSeek, MiniMax, Kimi (Moonshot), and Zhipu (GLM) with OAuth or an API key, and more are added over time. With your own keys, traffic goes directly from your machine to the provider and is not proxied through Orkas; official models run through Orkas's managed model service.O Orkas oferece modelos oficiais que você pode usar diretamente e também permite trazer seu próprio modelo. Você conecta provedores como OpenAI (GPT), Anthropic (Claude), Google (Gemini), DeepSeek, MiniMax, Kimi (Moonshot) e Zhipu (GLM) com OAuth ou uma chave API, e mais são adicionados ao longo do tempo. Com suas próprias chaves, o tráfego vai diretamente da sua máquina para o provedor e não passa pelo Orkas como proxy; os modelos oficiais usam o serviço de modelo gerenciado da Orkas.Orkas 提供可直接使用的官方模型，也支持自带模型。你可以用 OAuth 或 API 密钥接入 OpenAI（GPT）、Anthropic（Claude）、Google（Gemini）、DeepSeek、MiniMax、Kimi（月之暗面）、智谱（GLM）等供应商，后续还会不断增加。自带 key 时，流量从你的机器直连供应商、不经 Orkas 代理；官方模型走 Orkas 的托管模型服务。Orkas はそのまま使える公式モデルを提供し、モデルの持ち込みにも対応します。OAuth または API キーで OpenAI（GPT）、Anthropic（Claude）、Google（Gemini）、DeepSeek、MiniMax、Kimi（Moonshot）、Zhipu（GLM）などのプロバイダーを接続でき、対応は順次追加されます。自分のキーを使う場合、通信はあなたのマシンからプロバイダーへ直接送られ、Orkas を経由しません。公式モデルは Orkas のマネージド モデル サービスを利用します。
Where are my data and API keys stored?Onde meus dados e chaves API são armazenados?我的数据和 API 密钥存在哪里？データと API キーはどこに保存されますか？
On your machine. Your workspace — chats, files, knowledge base, and memory — is local-first by default, and your API keys are encrypted at rest with AES-256-GCM in a local config that never syncs. With your own keys, only your model call leaves the device, sent straight to the provider you chose; official models run through Orkas's managed model service.Na sua máquina. Seu espaço de trabalho – chats, arquivos, base de conhecimento e memória – é local-first por padrão, e suas chaves API são criptografadas em repouso com AES-256-GCM em uma configuração local que nunca sincroniza. Com suas próprias chaves, apenas a chamada do seu modelo sai do aparelho, enviada diretamente para o provedor que você escolheu; os modelos oficiais usam o serviço de modelo gerenciado da Orkas.在你的机器上。你的工作区——对话、文件、知识库和记忆——默认本地优先，API 密钥以 AES-256-GCM 加密存储在从不同步的本地配置中。自带 key 时，只有模型调用会离开设备、直接发往你所选的供应商；官方模型走 Orkas 的托管模型服务。あなたのマシンにあります。ワークスペース（チャット・ファイル・ナレッジベース・メモリ）は既定でローカルファーストで、API キーは同期されないローカル設定内に AES-256-GCM で暗号化保存されます。自分のキーを使う場合、端末を離れるのはモデル呼び出しだけで、選んだプロバイダーへ直接送られます。公式モデルは Orkas のマネージド モデル サービスを利用します。
Can Orkas run external CLI coding agents?Orkas pode executar agentes de codificação CLI externos?Orkas 能运行外部 CLI 编程 agent 吗？Orkas は外部 CLI コーディングエージェントを実行できますか？
Yes. Orkas can drive external CLI coding agents — Claude Code, Codex, OpenClaw, Hermes, and OpenCode — as local subprocesses and manage them beside its native team. You install the CLI yourself; Orkas auto-detects it on your PATH, checks a minimum version, and lets you summon it in chat like any other agent.Sim. Orkas pode conduzir agentes de codificação CLI externos – Claude Code, Codex, OpenClaw, Hermes e OpenCode – como subprocessos locais e gerenciá-los junto com sua equipe nativa. Você mesmo instala a CLI; Orkas o detecta automaticamente em seu PATH, verifica uma versão mínima e permite invocá-lo no chat como qualquer outro agente.可以。Orkas 能把外部 CLI 编程 agent——Claude Code、Codex、OpenClaw、Hermes、OpenCode——作为本地子进程驱动，并与原生团队一起管理。CLI 需要你自己安装；Orkas 会在 PATH 中自动检测、校验最低版本，并让你像其他 agent 一样在对话里召唤它。はい。Orkas は外部の CLI コーディングエージェント（Claude Code、Codex、OpenClaw、Hermes、OpenCode）をローカルのサブプロセスとして動かし、ネイティブのチームと並べて管理できます。CLI はご自身でインストールします。Orkas は PATH 上で自動検出し、最小バージョンを確認し、他のエージェントと同様にチャットから呼び出せるようにします。
Do I need an account to use Orkas?Preciso de uma conta para usar o Orkas?使用 Orkas 需要账号吗？Orkas を使うのにアカウントは必要ですか？
No account is required to start. Download the desktop client, open it, add a model key, and direct the lead agent. Optional features such as multi-device sync use an account, but the core local-first workflow runs without one.Nenhuma conta é necessária para iniciar. Baixe o cliente desktop, abra-o, adicione uma chave de modelo e direcione o agente líder. Recursos opcionais, como sincronização de vários dispositivos, usam uma conta, mas o workflow principal do local-first é executado sem ela.开始使用不需要账号。下载桌面客户端、打开、添加模型密钥，然后指挥主 agent。多设备同步等可选功能需要账号，但核心的本地优先工作流无需账号即可运行。開始にアカウントは不要です。デスクトップクライアントをダウンロードして開き、モデルキーを追加し、リードエージェントに指示します。マルチデバイス同期などの任意機能にはアカウントが必要ですが、中核となるローカルファーストのワークフローはアカウントなしで動作します。
# Data & privacy
Orkas is local-first: by default your agent configs, chats, knowledge bases, files, and memory live on your machine, and, with your own keys, your encrypted keys and model traffic never go through Orkas (official models run through Orkas's managed model service). 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.