Orkka Local

Get started on your own machine

Orkka Local runs the full AI-dev-team pipeline on your computer, free, using the AI subscriptions you already have — Claude, Codex (ChatGPT), Gemini, or GitHub Copilot. Your code never leaves your machine — agents work in git worktrees over your real local repositories.

1 · Prerequisites

Docker — Docker Desktop on Windows/macOS, or Docker Engine with the compose plugin on Linux. It must be running.

At least one AI CLI, logged in — Claude (Pro/Max subscription), Codex (ChatGPT subscription), Gemini, or GitHub Copilot. Any one is enough to run the pipeline; the QA browser-testing lane specifically needs Claude. For Claude, use the native installer, not npm — the npm version cannot be driven by Orkka's runner (see troubleshooting below):

$ irm https://claude.ai/install.ps1 | iex$ curl -fsSL https://claude.ai/install.sh | bash

Then run claude once, complete the login, and verify with claude -p "hi" — it should answer within a few seconds. (Codex: codex login. Gemini: run gemini and complete the sign-in. Copilot: copilot and sign in with GitHub.)

2 · Install & start

Windows (PowerShell):

$ irm https://raw.githubusercontent.com/orkka-ai/orkka-local-cli/main/install.ps1 | iex

macOS / Linux:

$ curl -fsSL https://raw.githubusercontent.com/orkka-ai/orkka-local-cli/main/install.sh | bash

Then:

$ orkka-local start

The first start downloads the container images (a few hundred MB — progress is shown), generates local secrets in ~/.orkka/, opens http://localhost:6750, and keeps running as the agent runner. Leave that window open while you work — it is the bridge between the UI and your machine.

3 · First steps

Create a project and pick your repositories right in the creation form (browse your machine, or create a brand-new repo from the folder picker). Then write a task, submit it, and watch your team take it from Drafting to a reviewed, mergeable change — every agent run uses your subscription, at no extra cost.

Useful along the way: the Repos page lets you switch each repo's default branch (the base agents branch from and merge into), and Settings controls how many tasks run in parallel.

4 · Staying updated

$ orkka-local update

Updates the CLI binary and pulls the latest container images; restart with orkka-local start. Two commands worth knowing: orkka-local status (container / API / login health) and orkka-local doctor (traces one agent run end-to-end — run it first whenever something misbehaves).

5 · Troubleshooting

Agent runs hang ~60s, then fail — chat replies never arrive

Almost always the npm-shim trap: claude resolves to the npm claude.cmd wrapper, which Orkka's runner cannot drive (hand-run commands work fine, which makes this maddening). Install the native CLI (see Prerequisites) and make sure ~/.local/bin comes first on your PATH. Verify with where.exe claude (Windows) — the .exe must be listed first. Then run orkka-local doctor: it detects this exact condition and prints the fix.

Status says Claude is not logged in (but you are)

Subscription tokens expire — run claude /login to refresh. On macOS, credentials live in the Keychain and orkka-local status reports logged in (macOS Keychain); if in doubt, claude -p "hi" is the truth test.

First start seems stuck on “Starting containers”

The first run downloads a few hundred MB of images. Recent versions stream the pull progress live — if yours shows nothing for minutes, update the CLI (re-run the install one-liner) and start again.

Replies feel slow — even a short answer takes several seconds

Expected for now: every message starts a fresh Claude CLI process on your machine, which costs a few seconds before the model even sees your text. Longer agent phases (planning, coding) dwarf this overhead. Making chat replies near-instant via session reuse is on the roadmap.

Rate-limit messages in task timelines

Agents share your Claude plan's usage limits, exactly as if you ran claude yourself. Lower the project's parallel-task setting, or wait for the limit window to reset.

“Ports are not available” on start — something already uses 5433

Another Postgres (or anything else) is bound to port 5433. Orkka only publishes that port as a debugging convenience — pick any free one: add ORKKA_PG_PORT=5434 to ~/.orkka/.env and run orkka-local start again.

Running on a headless server — can’t reach the UI

Everything binds to 127.0.0.1 on purpose (the stack is not meant to face a network). From your own machine, tunnel: ssh -L 6750:localhost:6750 -L 6752:localhost:6752 user@server and open localhost:6750 locally.

Designer images (raster) don’t generate

SVGs work out of the box. Raster images/GIFs need a Gemini API key: add ORKKA_GEMINI_API_KEY=<key> to ~/.orkka/.env and run orkka-local start again.

6 · Still stuck?

Run orkka-local doctor and include its output when you reach out — it captures exactly what we need to help.