open-cowork

Hand off computer tasks to an AI coworker — watch it work, approve from anywhere.

An open-source, cross-platform agentic coworker that sees a screen and acts on it — your own desktop, a cloud VM, or a browser. It streams every step live, pauses for your approval, and keeps spend visible and capped.

Runs on the Coasty Computer Use API out of the box — or bring your own LLM (OpenRouter · OpenAI · a local model). Your call.

Quickstart  ·  Bring your own LLM  ·  Automate your PC  ·  Features  ·  How it works  ·  Docs

_{Delegate a task → watch your coworker drive a browser, step by step → get the result. Runs with zero setup in demo mode.}

---

Quickstart

Prereqs: Node ≥ 22.5 (we use 24) · pnpm 10 (corepack enable).

git clone https://github.com/coasty-ai/open-cowork.git && cd open-cowork
pnpm install      # one install for the whole monorepo
pnpm desktop      # ← runs the desktop app: starts backend + web, opens the window

That's it — one command, zero config. pnpm desktop starts the backend and web UI, then opens the desktop app (the build that can drive your own screen). With no key set it runs in demo mode: a bundled mock server and a throwaway sandbox key — no account, no network, no billing.

Then, in the window:

1. Sign in with any email.
2. On Delegate, pick “This computer (local screen).”
3. Type a task → confirm the cost → watch it work. (Tip: put NEEDS_HUMAN in a task to see the approval flow pause and resume.)

🧠 Bring your own LLM (BYOK). Want it to run on your model instead of Coasty? Open Settings → Model provider and add OpenRouter, OpenAI, or a local model (Ollama / LM Studio). Coasty stays the default until you switch. Jump to BYOK ↓

⚠️ Local control moves your real mouse and keyboard. Stop with Cancel (or close the window), and start small — full safety notes in RUN_LOCALLY.md.

Ways to run

Goal	How	Model	Cost
Automate your own PC	pnpm desktop	Coasty or your own LLM	demo $0 · BYOK = your provider's rate
Web app only	pnpm dev → http://127.0.0.1:5173	Coasty	$0
Your Coasty account	add COASTY_API_KEY to .env	Coasty (real model)	sandbox key = $0
Bring your own LLM (BYOK)	Settings → Model provider	OpenRouter · OpenAI · Ollama	your provider's rate · local = $0

The only thing you ever have to set is COASTY_API_KEY — and even that's optional in demo mode. Everything else has a working default. Prefer your own model? That's BYOK — pick a provider in Settings and local runs use it. Full local-automation guide: RUN_LOCALLY.md.

Using your own Coasty account, webhooks & the cost warning

echo "COASTY_API_KEY=sk-coasty-test-…" > .env   # sandbox key — never bills
pnpm dev                                         # now talks to the real Coasty API

With a key set, pnpm dev does not start the mock and points the backend at the real Coasty API. Start with a sandbox key (sk-coasty-test-…) — it exercises the full real model and never bills. Switch to a live key only when you're ready to spend.

Webhooks (instant status without polling) require an https COWORK_PUBLIC_URL — Coasty only accepts HTTPS webhook URLs. open-cowork detects this: over a non-https URL it simply doesn't register a webhook (so run creation never fails) and state still syncs live via SSE + read-time reconcile. Set an https COWORK_PUBLIC_URL (a tunnel or your deployment — see DEPLOYMENT.md) to turn webhooks on.

⚠ Cost warning. With a live key (sk-coasty-live-…): runs bill $0.05/step, machines $0.05–0.09/hour running ($0.01 stopped), predict/session calls a few cents each. open-cowork always shows an estimate, requires explicit confirmation, enforces per-run budget caps server-side, and supports machine auto-terminate TTLs — but a live key is real money. All automated tests use the mock/sandbox path and never spend anything.

More commands

pnpm desktop       # full stack + the desktop app (local screen control) — one command
pnpm dev           # full stack, open the web app yourself at :5173
pnpm dev --no-web  # API only (mock + backend)
pnpm dev:mobile    # Expo / React Native  (or: pnpm --filter @open-cowork/mobile web)

Run the Electron app against an already-running stack (advanced)

With pnpm dev already running in another terminal:

pnpm dev:desktop   # builds the Electron bundles and opens the window only

pnpm desktop does both for you — start the stack and open the window — and shuts it all down when you close the window.

---

What you can do

• 💬 Delegate in chat — "rename these files and email the report" — and watch the agent execute it step by step with a live screen view.
• 🧠 Bring your own LLM (BYOK) — run local screen control on your model: OpenRouter, OpenAI, or a local model (Ollama / LM Studio / vLLM). Coasty is just the default. Details ↓
• 📺 Supervise runs — dashboard, durable event timeline (SSE with replay), cancel / resume / human-takeover from web, desktop, or phone.
• 🔁 Build workflows — a versioned JSON DSL (task · assert · if · loop · parallel · retry · human_approval) with instant validation, cost estimates, and hard server-side budget caps.
• 🖥️ Manage machines — provision Coasty cloud VMs, snapshot, stop, terminate, with live cost rates at every step.
• 📱 Stay in the loop across devices — start a run on your laptop; when it pauses for approval, the banner pops on your phone. Approve there.
• 💸 See cost at all times — wallet balance, per-run worst-case estimates, and an explicit confirm-the-cost handshake before anything billable starts.

Platform support

Capability	🖥️ Desktop	🌐 Web	📱 Mobile
Local screen control	✅ first-class	→ cloud machine	→ cloud machine
Cloud-machine control + live view	✅	✅	✅
Task chat + run dashboard	✅	✅	✅
Workflow builder	✅ full	✅ full	view + approve
Approvals / human takeover	✅	✅	✅
Cost / wallet view	✅	✅	✅

---

Bring your own LLM (BYOK)

Bring your own key, bring your own model. Local screen control defaults to Coasty's computer-use model — but you can point it at any OpenAI-dialect LLM instead. In the desktop app, open Settings → Model provider, pick a provider, choose a vision-capable model, and local runs use it. Coasty stays the default; switch back any time with one click. Nothing else in the app changes.

Provider	API key	Covers
OpenRouter	required	hundreds of models; vision read from OpenRouter's own modality metadata
OpenAI	required	gpt-4o, gpt-4.1, …
OpenAI-compatible	optional	Ollama, LM Studio, vLLM, Together, Groq — any …/v1 base URL

• 👁️ Vision is required. Computer use is screenshot-driven, so a model that can't see images is flagged and blocked with a clear message — never a blind, wasted run.
• 🏠 Local-first. A local model (e.g. Ollama at http://localhost:11434/v1) runs entirely on your machine — no key, no cloud, no spend.
• 🔑 Your key stays yours. BYO keys are encrypted with your OS keychain (Electron safeStorage — DPAPI / Keychain / libsecret), live only in the desktop process, are scrubbed from every error message, and never reach the web or mobile bundle.
• 👀 No surprise data egress. With a third-party model, your screenshots and prompts go to that provider — the app says so right in the confirm-the-cost dialog before a run starts.
• ☁️ Cloud-machine runs always use Coasty. BYO drives local (desktop) runs today; cloud BYO is a documented follow-up.

Built on the Vercel AI SDK: rate-limit (429) and transient errors retry with backoff, and if a model ignores structured output the response is recovered with a defensive JSON parse — so even smaller local models can drive the loop.

How it works

 You ──► open-cowork backend ──► Coasty API ──► a screen the agent drives
            │   (the ONLY place           ├─ your own desktop   (desktop app)
            │    the API key lives)       ├─ a Coasty cloud VM  (any client)
            └──► web / desktop / mobile   └─ a browser page     (Playwright)
                 live events, approvals, costs

One shared agent loop (screenshot → predict → act → repeat) drives any screen through a single Executor interface — LocalExecutor (your desktop), RemoteMachineExecutor (a cloud VM), or BrowserExecutor. The predict step is its own seam (@open-cowork/llm): Coasty is the default implementation, and a bring your own LLM is just another one behind the same contract, so the loop, executors, and UI don't care which is behind it. Clients never hold the Coasty key: they talk to the backend with short-lived session tokens, and the backend proxies to Coasty, verifies HMAC-signed webhooks, persists runs, and fans events out over SSE. Full design in ARCHITECTURE.md.

Security

COASTY_API_KEY exists only in the backend's environment. Browsers, Electron renderers, and the mobile app authenticate with short-lived session tokens and never see the key — enforced by tests that scan every client bundle and a runtime E2E assertion that watches every browser request for secret material. Bring-your-own-LLM keys follow the same rule: encrypted with the OS keychain (safeStorage), held only in the desktop process, scrubbed from every error, and kept out of the web/mobile bundles (the AI SDK is desktop-only). Coasty webhooks are verified with per-run HMAC secrets (constant-time compare, ±5-minute replay window) before they can touch any state. Threat notes in SECURITY.md.

---

Docs

Guide	What's inside
RUN_LOCALLY.md	Automate your own PC with the desktop app — step by step
ARCHITECTURE.md	Monorepo map, the Executor abstraction, agent loop, realtime + data model
SECURITY.md	Key custody, HMAC, trust boundary, threat table
DEPLOYMENT.md	Running the backend + each client in production
COOKBOOK.md	Recipes: cross-device approval, workflows, scripting the loop
DECISIONS.md · CONTRIBUTING.md · SUMMARY.md	Stack choices · how to contribute · what was built + coverage

Project layout

packages/core       Coasty client, agent loop, workflow DSL, cost estimator, HMAC — isomorphic, zero deps
packages/executor   Executor abstraction: LocalExecutor (native), RemoteMachineExecutor (VM), BrowserExecutor
packages/llm        BYO LLM provider seam: Coasty + OpenAI/OpenRouter/Ollama via the Vercel AI SDK (desktop-only)
packages/ui         Shared React design system + domain components
apps/backend        Fastify: auth, Coasty proxy (sole key holder), webhooks, SQLite, SSE fan-out, budgets
apps/web            Vite + React SPA (also hosted by the desktop shell)
apps/desktop        Electron shell + LocalRunManager (local screen control)
apps/mobile         Expo / React Native companion (monitor + approve)
tools/mock-coasty   Full offline mock of the Coasty API (REST + SSE + signed webhooks)
e2e                 Playwright end-to-end flows (web + desktop)

Commands

Command	What
pnpm dev	mock + backend + web, wired together (--no-web for API only)
pnpm doctor	preflight: Node, deps, key shape
pnpm test	every unit + integration suite (offline, no spend)
pnpm typecheck · pnpm lint · pnpm format	strict s