Layer 1 of OPE-252. Until now a provider's page offered only the curated rows,
and a new model had to be typed in by id with nothing checking it.
Backend
- providers/live_models.py asks the configured provider's own model list with
the user's key (Anthropic and Gemini their way, Azure at its endpoint, the
OpenRouter sign-in at OpenRouter, every OpenAI-compatible vendor at its base
URL) through the shared probe client, reads the three answer shapes in use,
keeps chat models only, newest first, and carries whatever facts the list
gives: context window, tool and image support, release date. The ChatGPT
plan, Bedrock, Vertex and Ark have no list and say so.
- GET /v1/providers/{name}/catalog: the listing merged with the curated rows,
cached a day per provider (Refresh asks again). Each row says where its facts
come from (catalog, provider, unverified), whether it is in the picker,
recommended, new since the check before, and on the key at all. "New" is
what the list gained since the previous check at least an hour old, so two
refreshes in a row do not swallow the badge; the first look marks nothing.
A failed re-ask keeps the last list and says why; a failed first ask falls
back to the curated rows.
- add_model refuses an id the key's own list does not carry ("Not available on
this key") and names the closest ids; nothing changes for local servers,
providers without a list, or before a list was asked.
- The listing's facts for picker models the catalog does not know go to
live_facts.json; the engine's window resolution and capabilities_for read
them. Settings answers model_verification per picker model and extends
labels and windows with the listing's. A window the user saved now beats
the catalog's (it used to lose).
- The overflow learner: when a provider refuses a long prompt and names its
limit, the engine saves that figure as the model's context window when ours
was unknown or larger (compaction.overflow_limit reads the figure from the
OpenAI, Anthropic, vLLM and generic wordings).
GUI
- ProviderModels on a keyed provider's page: "N models on this key · checked
2 min ago · Refresh", then New since last check, Recommended, All models
(searchable, folds at 12), each row a tick for the picker with its context,
images, new / unverified / not on this key tags and Make default. A typed id
the key cannot call shows the refusal and "Did you mean" buttons. Providers
without a list keep the curated checklist under the reason.
- The provider card shows "N new" when the list gained models.
- The model settings dialog lets the user set the context window of a cloud
model the catalog does not know, and says whether the figure came from the
provider's list or nowhere.
Tests: tests/test_live_models.py (45: the answer shapes incl. Gemini, Together,
Mistral, Cohere, Groq and garbage; every keyed provider has a request or a
reason; the environment key; fetch never raises; the cache, Refresh, the
restart, "new" across the hour rule, failures; add_model refusal with
suggestions and the cases it must not gate; the facts reaching settings,
the engine and capabilities_for; the window order; the overflow learner;
the route), overflow_limit in test_compaction, ProviderModels.test.tsx (8)
and ProviderGroups.badge.test.tsx. Backend suites around it: 230 passed;
whole GUI suite 769 passed; tsc clean.
OpenWorker
A Desktop App for everyday work.
A Harness SDK to power your AI ideas.
openworker.com · Desktop App · Harness SDK · Issues
Use the OpenWorker Desktop App to research, write, review code, and carry out tasks across the tools you already use. Or build your own agentic desktop and web apps with the OpenWorker Harness SDK.
Bring your choice of cloud or local models. Set permissions for your agents and decide which actions need your approval.
This README mainly covers the OpenWorker Desktop App. For SDK setup, examples and architecture, see the OpenWorker Harness SDK README.
Use the OpenWorker Desktop App
An AI coworker for your everyday work. Go from a request to a prepared brief, an organized folder, or a reviewed pull request.
It runs on your machine. Bring your own model key or run locally with Ollama, and choose which integrations it can access. Commands can run inside an NVIDIA OpenShell sandbox. See Governed by design for its approval and safety controls.
⬇ macOS (Apple Silicon) macOS 12+ · signed & notarized · auto-updates
⬇ Windows 10/11 (x64) builds are not yet code-signed, so SmartScreen will warn; signing is in progress
Open the app, add a model key (or point it at Ollama), and ask for something real.
The OpenWorker Desktop App is in open beta and supports automatic updates. Issues welcome as we polish rough edges.
Build agentic apps using OpenWorker Harness SDK
Bring agentic capabilities to your own desktop app, web app or local utility. Build the product experience while OpenWorker handles the agent loop, tool calls, approvals, streaming and durable sessions.
Use the TypeScript SDK from npm, or embed the Rust engine in your application. Start with one agent. Add sub-agents, teams, OpenShell sandboxing and observability as your application grows.
npm install @openworkerai/harness-sdk
Explore the Harness SDK → · Desktop guide · Web guide · Build with Codex or Claude Code
The rest of this README focuses on the OpenWorker Desktop App. For SDK documentation, continue with the Harness SDK README.
What you can do with the Desktop App
| Your work | How OpenWorker helps |
|---|---|
| Research and create | Turn notes, files and research into briefs, documents, spreadsheets and reports. |
| Review security risks | Scan code and dependencies, review cloud configuration, and investigate incidents. Proposed code fixes are re-scanned and reviewed before approval. |
| Work across your tools | Bring together GitHub, Slack, email, calendars and other connected apps. Add tools through MCP. |
| Delegate from Slack | Mention @OpenWorker; the task runs on your desktop and the reply returns to the thread. |
| Automate recurring work | Schedule morning briefs, weekly reports and other repeatable tasks, with transcripts to review. |
| Choose your model | Connect a cloud provider or use a local model through Ollama and other compatible servers. |
| Control agent actions | Review approvals, inspect recorded actions, and isolate supported commands with OpenShell or platform sandboxing. |
Specialist coworkers come with tools and instructions for a particular job. Security coworkers ship first.
Try your first task
Start with a folder of meeting notes. No connected apps are needed for this example.
- Choose a model. Open Settings → Models & Keys and connect a provider or local model.
- Choose your working folder. Give the session access to a folder containing a few text or Markdown notes.
- Ask for a brief. Paste the request below, follow the tool activity, and review any approval requests before continuing.
Read the meeting notes in this folder. Create a one-page brief with the key decisions, open questions and next steps. Save it as
brief.md. Leave the original notes unchanged and ask before writing the brief.
Open brief.md in the working folder and review it. Continue in the same session: “Make the next steps more specific, and flag anything without an owner.”
Governed by design
The Desktop App combines approvals, recorded tool activity and optional sandboxing. You can review proposed actions and decide how much autonomy to allow.
How approvals, audit trails and sandboxing work
Governance is the architecture, not a plugin - the agent can't grant itself new permissions, and no prompt can talk it past a gate. Four tiers, all in this repo:
-
Hard floors. A set of dangerous and irreversible operations is human-only, always. No mode - including full auto-approve - lowers these floors; they always escalate to you.
-
A ladder of earned autonomy. Actions are approval-gated by default. One-off approvals can graduate into standing rules, then into config allowlists - each step explicit, visible, and revocable. In auto-approve mode a reviewer model lets routine actions through and escalates anything it isn't sure about to you; repeated denials trip a circuit breaker that pauses the reviewer and hands control back. Reviewer verdicts are judgments, not guarantees - the floors and the audit trail are what backstop them.
-
An audit trail that answers "who did this, and why?" Every tool call is recorded with its approval provenance - auto-approved, user-approved, or denied, with the reviewer's reasoning attached - and persisted with the conversation.
-
A sandbox for what the agent runs. A session's commands and file tools can run inside an NVIDIA OpenShell sandbox — one Linux container per agent that holds the session's folders and nothing else: no keys, no other files, and only an allow list of network hosts. The agent loop, the model keys and the connectors stay outside the wall, so a prompt injection that reaches a command lands in a box that holds nothing. On a Mac the same protection is available with nothing to install, through the sandbox built into macOS; on Windows, through a hidden local account that cannot see your profile. See docs/openshell.md, docs/macos-sandbox.md and docs/windows-sandbox.md.
Unattended runs never self-approve: their asks park in an inbox until a human answers. Found a vulnerability? See SECURITY.md.
Bring your own model
Connect OpenAI, Anthropic, Google Gemini, OpenRouter and other providers, or use a local model through Ollama, LM Studio, llama.cpp or vLLM. Choose and switch models in Settings → Models & Keys.
See Desktop App model setup for provider options, account connections and custom endpoints. SDK developers can use the separate models and credentials guide.
Desktop App privacy
The OpenWorker Desktop App is local-first. Everything lives on your machine: the agent loop, your conversations, connector tokens, and model keys - all in the app's local secret store. The only cloud piece is a small service that brokers OAuth handshakes for connectors. You can always use the App without signing-in - use the connectors via manually-created credentials/API-keys.
Documentation
| Start here | What you’ll find |
|---|---|
| Desktop App model setup | Cloud providers, OpenRouter accounts and custom endpoints. |
| Local models | Connect models running on your own hardware. |
| Approvals and safety | How the Desktop App handles permissions and records actions. |
| NVIDIA OpenShell | Set up sandboxed command and file execution for the Desktop App. |
| Harness SDK | SDK installation, architecture and examples. |
| Build a desktop app · Build a web app | Learn the SDK through working applications. |
| App-building skill | Build with Codex or Claude Code. |
| SDK troubleshooting | Diagnose SDK setup and runtime problems. |
Run the Desktop App from source
Development setup and architecture
The Desktop App uses a Python agent engine. The Harness SDK provides a separate Rust engine for applications you build.
Under the hood:
┌────────────────────────────────────────────────┐
│ OpenWorker Desktop App │ native shell + GUI
├────────────────────────────────────────────────┤
│ local agent server (Python) │ engine · tools · connectors - built on aisuite
├───────────────┬────────────────┬───────────────┤
│ your files │ your tools │ your model │ everything runs with your keys,
│ & terminal │ 25+ connectors │ any provider │ on your machine
└───────────────┴────────────────┴───────────────┘
Prerequisites: Python 3.10+, Node 20+, and (for the desktop shell) the Rust toolchain via rustup.
git clone https://github.com/andrewyng/openworker
cd openworker
# 1. One-time bootstrap - creates the Python venv at .venv
# (on Windows, run from Git Bash or WSL)
bash packaging/setup_dev_env.sh
# 2. Start the local agent server
.venv/bin/python -m coworker.server.run --cwd ~/some/project --port 8765
# (Windows: .venv\Scripts\python -m coworker.server.run ...)
# 3. In a second terminal, start the UI
cd surfaces/gui
npm install
npm run dev # browser UI on the Vite dev port
The standalone server creates a per-launch token at
<state-dir>/sidecar-8765.token; Vite reads that user-only file when it starts.
For direct API calls, send its value in the X-OpenWorker-Token header. The
desktop app uses an in-memory launch token instead and never writes it to disk.
To run the full desktop app instead of the browser UI, replace step 3 with npm run tauri dev (from surfaces/gui/) - the Tauri shell launches the window and supervises the server itself.
Tests: .venv/bin/pytest (server), npm test and npm run e2e in surfaces/gui (GUI unit + hermetic end-to-end). Desktop bundles are built with packaging/build_dmg.sh / packaging/build_windows.ps1.
Repository layout
| Directory | What's in it |
|---|---|
coworker/ |
Python backend - agent engine, model providers, connectors, MCP client, memory, automations |
harness/ |
Rust agent runtime, Rust/TypeScript SDKs, service and SDK examples |
surfaces/gui/ |
Desktop app - React UI + Tauri shell that supervises the server |
stt/ |
Speech-to-text sidecar (Rust) for voice input |
packaging/ |
Installer builds (macOS DMG, Windows), auto-update manifest, dev bootstrap |
docs/ |
Design specs and decision logs |
tests/ |
Backend test suite |
Built on aisuite
The OpenWorker Desktop App's engine is built on aisuite, a lightweight Python library providing a unified chat-completions API across LLM providers and an agents layer with tools, toolkits, and MCP support. If you want to build your own agent harness rather than use ours, start there; this repo is a working reference for what aisuite can carry.
OpenWorker was originally developed inside the aisuite repository before moving to its own home here; thanks to the aisuite contributors whose work it builds on.
Contributing
Contributions and bug reports are welcome - open an issue or a pull request. The app updates itself, so fixes reach installs quickly. For any PR, please attach screenshots of what was broken and how it is fixed now. We will shortly add features that you can contribute to. Please note that we are actively developing based off a internal list and goal, so we may not approve PRs that add features that are already under-development or deviates from our vision.
License
MIT - see LICENSE.
