How to Install and Run Orkas
This guide is based on the open-source project Orkas by Orkas-AI, licensed under MIT. StackGuide AI is not affiliated with Orkas.
Orkas is a local-first, multi-agent desktop app: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents, plus the coding and personal agents you already use, such as Claude Code, Codex, OpenCode, OpenClaw and Hermes-Agent, to deliver finished files. As of October 31, 2026, its GitHub repository has 5,974 stars.
What Orkas is, and who it is for
The Commander handles general work itself and delegates specialist work through three tools: dispatch_to runs a named agent and returns its result, hand_off_to transfers the remaining work to that agent, and run_worker runs an anonymous, isolated sub-task without conversation history or a named agent's skills. Around that sit projects with shared goals, memory and files, to-do lists with auto-advance, scheduled automations, and a Library that extracts documents into passages and stores a local SQLite vector index, with its embedding model running on your machine.
It suits people and small teams whose work keeps moving across days: research and reports, content, store operations, client work, product launches and building small apps, where one chat answer is not the deliverable. It is not a single all-purpose chatbot, and it is not a code library to embed in your own app. The README is explicit on both points.
There are two different builds, and the distinction matters. The packaged app, for macOS and Windows, signs you in, includes a built-in Orkas model or your own keys, and adds project collaboration, app publishing, cloud sync and more; the README says it starts with 500 free credits. The source build, currently the way to run Orkas on Linux, uses your own keys or a local endpoint, and does not yet support shared projects, cloud sync or web-app publishing. Choose the build that matches whether you want cloud features or a keys-only local run, and check the current terms on orkas.ai before relying on any credit offer.
Prerequisites
- For the packaged app: macOS 12 or later (Apple Silicon or Intel) or Windows 10 or later, and a sign-in for the packaged app's account.
- For the source build: Node.js 22.12 or later, macOS, Windows 10 or later, or glibc 2.34 or later Linux on x64 or arm64. Keep Python 3 and a C or C++ build toolchain available for the uncommon native-module source-build fallback. Alpine and other musl-based distributions are not supported.
- Model access: a built-in Orkas model in the packaged app, or your own API key, OAuth, or local endpoint in the source build. Add these in Settings, then AI Providers.
- The CLI agents you want to coordinate, already installed: Orkas runs Claude Code, Codex, OpenCode, OpenClaw and Hermes-Agent as local sessions, so install the ones you want it to use before asking it to coordinate them.
Step 1: Install Orkas
Packaged app (recommended in the README). Download Orkas from the official download page, which detects your system and starts the right installer, then sign in and add a model provider.
From source. Clone and run the launcher for your system:
git clone https://github.com/Orkas-AI/Orkas.git
cd Orkas
./run.sh # macOS / Linux
run.cmd # WindowsThe first launch installs the locked npm dependency tree and prepares pinned Python, Node, an embedding model of about 95 MB, OfficeCLI, FFmpeg, whisper.cpp and multilingual speech model resources. It also creates a workspace under ~/.orkas/ on macOS and Linux, or under a .orkas folder on the smallest non-system drive on Windows. Then open Settings, then AI Providers to add an API key or OAuth. Allow that first launch to finish; interrupting a first-time resource download is a common cause of a half-installed state.
If native dependencies fail, the README says to use Node.js 24 LTS, minimum 22.12.0, then run npm run native:repair from the checkout, or npm run native:check for a check without installation.
Step 2: Give the Commander one finished deliverable to produce
Start with a single, checkable job, for example a monthly client report from a template, a research report with sources, or a bug fix with tests. State the goal, the files it may read, and what finished looks like, then let the Commander plan the steps and bring in specialists. Watch the to-do list: the Commander should turn the goal into to-dos and show progress, not just stream text.
When the work comes back, check it the way you would check a colleague's work: open the files, verify the sources, and run the tests or the numbers yourself. Orkas keeps file reads, file changes and command executions as structured records that can survive context compaction, but a record of an action is not proof the action was correct.
Common problems and fixes
| Problem | Fix |
|---|---|
| Native dependency errors on first launch | Use Node.js 24 LTS, minimum 22.12.0, then run npm run native:repair from the checkout, as the README instructs. |
| Cloud sync or shared projects are missing | Those are packaged-app features only. The open-source build does not support them yet, so use the packaged app if you need them. |
| A CLI agent is not available to Orkas | Install that agent yourself first. Orkas runs the CLI agents you already have installed as local sessions; it does not install Claude Code, Codex or the others for you. |
| First launch seems to download a lot | That is expected: the launcher prepares the dependency tree, the embedding model, OfficeCLI, FFmpeg and speech resources. Let it finish before judging the install. |
| Linux fails to start | Check the glibc requirement of 2.34 or later, and that you are not on Alpine or another musl-based distribution, which the README says is not supported. |
FAQ
Is Orkas a hosted service? No, in the README's own framing: it is a desktop app, not a hosted SaaS, and data and keys stay on your own disk in the local-first design. The packaged app adds cloud sync and publishing, so check which features you enable if that distinction matters to you.
Does Orkas replace Claude Code or Codex? No. It runs them as members of its team, alongside its own specialists, so one chat can fix a bug, review the change and draft the release note without you choosing a single agent for everything.
What are the 16 specialists? Built-in agents covering research and analysis, content and media, building and office work, and e-commerce, each with its own skills, memory and tools. The README lists them in full, with more agents in its marketplace.
Can it run automations on a schedule? Yes, hourly, daily, weekly or monthly, and from version 1.9 each automation catches up its most recent missed run within 12 hours when the computer wakes or Orkas starts. It runs on your computer, so a machine that is off cannot run anything.
Licence and attribution
Orkas is licensed under MIT. In plain terms, and not as legal advice: you may use, copy, modify and distribute the open-source code, including commercially, provided you keep the copyright and licence notices with the code. That licence covers the repository code; the packaged app's account, built-in model, credits and cloud features are a service with its own terms, so check orkas.ai for those before depending on them.
What to try next
Once one deliverable comes back correct, set up a project with its own goals, rules, memory and files, and a to-do list that auto-advances. That is the step where Orkas stops being a chat window and starts being a team workspace.
This guide was checked against the official README and repository as of October 31, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands below are the ones the official README publishes.