diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c9f48e734..0cfbbc2de 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -31,9 +31,8 @@ Auto-detection can exist as a convenience, but should be tiered and explainable: The readiness check should be a clear, single command (e.g. `docker info`) and the UI should show the exact error output when it fails. ## Minimal use of Tauri -We move most of the functionality to the openwork server which interfaces mostly with FS and proxies to opencode. - +We move most of the functionality to the openwork server which interfaces mostly with FS and proxies to opencode. ## Filesystem mutation policy @@ -56,12 +55,12 @@ Guidelines: When OpenWork is edited from `openwork-enterprise`, architecture and runtime behavior should be sourced from this document. -| Entry point | Role | Architecture authority | -| --- | --- | --- | -| `openwork-enterprise/AGENTS.md` | OpenWork Factory multi-repo orchestration | Defers OpenWork runtime flow, server-vs-shell ownership, and filesystem mutation behavior to `_repos/openwork/ARCHITECTURE.md`. | -| `openwork-enterprise/.opencode/agents/openwork-surgeon.md` | Surgical fix agent for `_repos/openwork` | Uses `_repos/openwork/ARCHITECTURE.md` as the runtime and architecture source of truth before changing product behavior. | -| `_repos/openwork/AGENTS.md` | Product vocabulary, audience, and repo-local development guidance | Refers to `ARCHITECTURE.md` for runtime flow, server ownership, and architectural boundaries. | -| Skills / commands / agents that mutate workspace state | Capability layer on top of the product runtime | Should assume the OpenWork server path is canonical for workspace creation, config writes, `.opencode/` mutation, and reload signaling. | +| Entry point | Role | Architecture authority | +| ---------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `openwork-enterprise/AGENTS.md` | OpenWork Factory multi-repo orchestration | Defers OpenWork runtime flow, server-vs-shell ownership, and filesystem mutation behavior to `_repos/openwork/ARCHITECTURE.md`. | +| `openwork-enterprise/.opencode/agents/openwork-surgeon.md` | Surgical fix agent for `_repos/openwork` | Uses `_repos/openwork/ARCHITECTURE.md` as the runtime and architecture source of truth before changing product behavior. | +| `_repos/openwork/AGENTS.md` | Product vocabulary, audience, and repo-local development guidance | Refers to `ARCHITECTURE.md` for runtime flow, server ownership, and architectural boundaries. | +| Skills / commands / agents that mutate workspace state | Capability layer on top of the product runtime | Should assume the OpenWork server path is canonical for workspace creation, config writes, `.opencode/` mutation, and reload signaling. | ### Agent access to server-owned behavior @@ -86,37 +85,38 @@ Tauri or other native shell behavior remains the fallback or shell boundary for: If an agent needs one of the server-owned behaviors above and only a Tauri path exists, treat that as an architecture gap to close rather than a parallel capability surface to preserve. ## opencode primitives -how to pick the right extension abstraction for + +how to pick the right extension abstraction for @opencode opencode has a lot of extensibility options: mcp / plugins / skills / bash / agents / commands - mcp -use when you need authenticated third-party flows (oauth) and want to expose that safely to end users -good fit when "auth + capability surface" is the product boundary -downside: you're limited to whatever surface area the server exposes + use when you need authenticated third-party flows (oauth) and want to expose that safely to end users + good fit when "auth + capability surface" is the product boundary + downside: you're limited to whatever surface area the server exposes - bash / raw cli -use only for the most advanced users or internal power workflows -highest risk, easiest to get out of hand (context creep + permission creep + footguns) -great for power users and prototyping, terrifying as a default for non-tech users + use only for the most advanced users or internal power workflows + highest risk, easiest to get out of hand (context creep + permission creep + footguns) + great for power users and prototyping, terrifying as a default for non-tech users - plugins -use when you need real tools in code and want to scope permissions around them -good middle ground: safer than raw cli, more flexible than mcp, reusable and testable -basically "guardrails + capability packaging" + use when you need real tools in code and want to scope permissions around them + good middle ground: safer than raw cli, more flexible than mcp, reusable and testable + basically "guardrails + capability packaging" - skills -use when you want reliable plain-english patterns that shape behavior -best for repeatability and making workflows legible -pro tip: pair skills with plugins or cli (i literally embed skills inside plugins right now and expose commands like get_skills / retrieve) + use when you want reliable plain-english patterns that shape behavior + best for repeatability and making workflows legible + pro tip: pair skills with plugins or cli (i literally embed skills inside plugins right now and expose commands like get_skills / retrieve) - agents -use when you need to create tasks that are executed by different models than the main one and might have some extra context to find skills or interact with mcps. + use when you need to create tasks that are executed by different models than the main one and might have some extra context to find skills or interact with mcps. -- commands -`/` commands that trigger tools +- commands + `/` commands that trigger tools These are all opencode primitives you can read the docs to find out exactly how to set them up. @@ -124,12 +124,13 @@ These are all opencode primitives you can read the docs to find out exactly how - uses all these primitives - uses native OpenCode commands for reusable flows (markdown files in `.opencode/commands`) -- adds a new abstraction "workspace" is a project folder and a simple .json file that includes a list of opencode primitives that map perfectly to an opencode workdir (not fully implemented) - - openwork can open a workpace.json and decide where to populate a folder with thse settings (not implemented today +- adds a new abstraction "workspace": a project folder plus OpenWork-managed connection/config state that still maps cleanly to an OpenCode workdir +- the current product surface treats local and remote workers through the same workspace/session shell rather than a separate dashboard concept ## Repository/component map - `/apps/app/`: OpenWork app UI (desktop/mobile/web client experience layer). + - the settings shell owns the workspace list plus user-facing tabs for general settings, skills, extensions, automations, messaging, appearance, and recovery. - `/apps/desktop/`: Tauri desktop shell that hosts the app UI and manages native process lifecycles. - `/apps/server/`: OpenWork server (API/control layer consumed by the app). - `/apps/orchestrator/`: OpenWork orchestrator CLI/daemon. In `start`/`serve` host mode it manages OpenWork server + OpenCode + `opencode-router`; in daemon mode it manages workspace activation and OpenCode lifecycle for desktop runtime. @@ -579,8 +580,9 @@ This is optional and not required for non-technical MVP. OpenWork enforces folder access through **two layers**: 1. **OpenWork UI authorization** - - user explicitly selects allowed folders via native picker - - OpenWork remembers allowed roots per profile + - workspace root access is implicit for the active workspace + - extra folders are managed from the Authorized folders panel in Settings + - OpenWork persists those extra directories through workspace config updates on the OpenWork server 2. **OpenCode server permissions** - OpenCode requests permissions as needed diff --git a/PRODUCT.md b/PRODUCT.md index de12daa30..cbbec43b6 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -1,265 +1,63 @@ -# OpenWork Product +## Product -## Target Users +OpenWork helps individual create, consume, and maintain their agentic workflows. -> Bob the IT guy. -Bob might already use opencode, he can setup agents and workflows and share them with his team. The only thing he needs is a way to share this. The way he does is by using OpenWork and creating "workpaces". +OpenWork helps companies share their agentic workflows and provision their entire team. -> Susan in accounting +The chat interfaces is where people consume the workflows. -Susan in accounting doesn't use opencode. She certaintly doesn't paly aorund to create workflow create agents. She wants something that works. -Openwork should be given to give her a good taste of what she can do. -We should also eventually guide ther to: -- creating her own skills -- adding custom MCP / login into mcp oauth servers through ui) -- adding skills from a list of skills -- adding plugins from a list of plugins -- create her own commands +Interfaces for consuming workflows: +- Desktop app +- Slack +- Telegram +What is a "agentic workflow": +- LLM providers +- Skills +- MCP +- Agents +- Plugins +- Tools +- Background Agents +Where are workflows created: +- Desktop app (using slash commands like `/create-skills`) +- Web App +- [We need better places for this to happen[ -1. **knowledge worker**: "Do this for me" workflows with guardrails. -2. **Mobile-first user**: start/monitor tasks from phone. -3. **Power user**: wants UI parity + speed + inspection. -4. **Admin/host**: manages a shared machine + profiles. +Where are workflows maintain: +- In OpenWork Cloud (internal name is Den). -## Success Metrics +Where are workflow hosted: +- Local Machine +- Remote via a OpenWork Host (CLI or desktop) +- Remote on OpenWork Cloud (via Den sandbox workers) -- < 5 minutes to first successful task on fresh install. -- > 80% task success without terminal fallback. -- Permission prompts understood/accepted (low confusion + low deny-by-accident). -- UI performance: 60fps; <100ms interaction latency; no jank. +## Current OpenWork Cloud flow -## Product Primitives (What OpenWork Exposes) +- Users can sign in with the standard web auth providers or accept an org invite through the hosted join flow. +- Invite signup keeps the invited email fixed, verifies the user by email code, and then drops them into the org join path. +- Org creation can trigger checkout up front when billing is required, and launch attempts surface org limits when the current plan does not allow more workers or members. +- After a worker is ready, the user connects from the OpenWork app with `Add a worker` -> `Connect remote`, or opens the generated deep link directly. -OpenWork must feel like "OpenCode, but for everyone." +## Team distribution -### 1) Tasks +- Organizations can publish shared skill hubs so members discover approved skills from one managed place instead of collecting local-only installs by hand. +- Org admins can now manage teams directly in the hosted dashboard and grant each skill hub to the exact teams that should inherit it. +- Team members install those approved skills from the desktop Skills page through the OpenWork Cloud catalog instead of importing local files manually. +- Power users can also share an installed desktop skill back to the org hub or publish a public install link from the same Skills page. -- A Task = a user-described outcome. -- A Run = an OpenCode session + event stream. +## Actors +Bob IT guy makes the config. +Susan the accountant consumes the config. -### 2) Plans / Todo Lists +Constraints: +- We use standards were possible +- We use opencode where possible +- We stay platform agnostic -OpenWork provides a first-class plan UI: -- Plan is generated before execution (editable). -- Plan is updated during execution (step status + timestamps). -- Plan is stored as a structured artifact attached to the session (JSON) so it's reconstructable. - -Implementation detail: - -- The plan is represented in OpenCode as structured `parts` (or a dedicated "plan message") and mirrored in OpenWork. - -### 3) Steps - -- Each tool call becomes a step row with: - - tool name - - arguments summary - - permission state - - start/end time - - output preview - -### 4) Artifacts - -Artifacts are user-visible outputs: - -- files created/modified -- generated documents/spreadsheets/presentations -- exported logs and summaries - -OpenWork lists artifacts per run and supports open/share/download. - -### 5) Audit Log - -Every run provides an exportable audit log: - -- prompts -- plan -- tool calls -- permission decisions -- outputs - -## UI/UX Requirements (Slick as a Core Goal) - -### Design Targets - -- premium, calm, high-contrast -- subtle motion, springy transitions -- zero "developer vibes" in default mode - -### Performance Targets - -- 60fps animations -- <100ms input-to-feedback -- no blocking spinners (always show progress state) - -### Mobile-first Interaction - -- bottom navigation -- swipe gestures (dismiss, approve, cancel) -- haptics for major events -- adaptive layouts (phone/tablet) - -### Accessibility - -- WCAG 2.1 AA -- reduced motion mode -- screen-reader labels for steps + permissions - -## Design Reference - -use the design from ./design.ts that is your core reference for building the entire ui - -## Functional Requirements - -### Onboarding - -- Host vs Client selection -- workspace selection (Host) -- connect to host (Client) -- provider/model setup -- first-run "hello world" task - -### Cloud Worker Onboarding (Current) - -- Sign in (or sign up) on OpenWork cloud control surface. -- Launch worker with a human-readable name. -- If needed, complete checkout and return. -- Select launched worker from list/detail shell. -- Connect from OpenWork app via `Add a worker` -> `Connect remote`. -- Prefer one-click deep link when available; always provide manual URL + token fallback. - -### Task Execution - -- create task -- plan preview and edit -- run with streaming updates -- pause/resume/cancel -- show artifacts and summaries - -### Permissions - -- clear prompts with "why" -- allow once/session -- audit of decisions - -### Commands - -- save a task as a command -- arguments + quick run - -### Scheduling (Future) - -- schedule command runs -- notify on completion - -## User Flow Map (Exhaustive) - -### 0. Install & Launch - -1. User installs OpenWork. -2. App launches. -3. App shows "Choose mode: Host / Client". -4. Host: start local OpenCode via SDK. -5. Client: connect flow to an existing host. - -### 1. First-Run Onboarding (Host) - -1. Welcome + safety overview. -2. Workspace folder selection. -3. Allowed folders selection (can be multiple). -4. Provider/model configuration. -5. `global.health()` check. -6. Run a test session using `session.create()` + `session.prompt()`. -7. Success + sample commands. - -### 2. Pairing Onboarding (Client / Mobile) - -1. User selects "Client". -2. UI explains it connects to a trusted host. -3. User scans QR code shown on host device. -4. Client verifies connection with `global.health()`. -5. Client can now list sessions and monitor runs. - -### 3. Runtime Health & Recovery - -1. UI pings `global.health()`. -2. If unhealthy: - - Host: attempt restart via `createOpencode()`. - - Client: show reconnect + diagnostics. - -### 4. Quick Task Flow - -1. User types goal. -2. OpenWork generates plan (structured). -3. User approves. -4. Create session: `session.create()`. -5. Send prompt: `session.prompt()`. -6. Subscribe to events: `event.subscribe()`. -7. Render streaming output + steps. -8. Show artifacts. - -### 5. Guided Task Flow - -1. Wizard collects goal, constraints, outputs. -2. Plan preview with "risky step" highlights. -3. Run execution with progress UI. - -### 6. File-Driven Task Flow - -1. User attaches files. -2. OpenWork injects context into session. -3. Execute prompt. - -### 7. Permissions Flow (Any) - -1. Event indicates permission request. -2. UI modal shows request. -3. User chooses allow/deny. -4. UI calls `client.permission.reply({ requestID, reply })`. -5. Run continues or fails gracefully. - -### 8. Cancel / Abort - -1. User clicks "Stop". -2. UI calls `client.session.abort({ sessionID })`. -3. UI marks run stopped. - -### 9. Summarize - -1. User taps "Summarize". -2. UI calls `client.session.summarize({ sessionID })`. -3. Summary displayed as an artifact. - -### 10. Run History - -1. UI calls `session.list()`. -2. Tap a session to load `session.messages()`. -3. UI reconstructs plan and steps. - -### 11. File Explorer + Search - -1. User searches: `find.text()`. -2. Open file: `file.read()`. -3. Show changed files: `file.status()`. - -### 12. Commands - -1. Save a plan + prompt as a command. -2. Re-run command creates a new session. - -### 13. Multi-user (Future) - -- separate profiles -- separate allowed folders -- separate providers/keys - -### 14. Hosted Cloud Worker Connect Flow (Current) - -1. User opens OpenWork cloud control page and authenticates. -2. User launches a worker (with optional checkout). -3. UI polls until worker is healthy. -4. UI resolves workspace-scoped connect URL (`/w/ws_*`) and access token. -5. User clicks `Open in OpenWork` or copies manual credentials. -6. In OpenWork app, user uses `Add a worker` -> `Connect remote` and starts working. +How to decide if OpenWork should do something: +- Does it help Bob share config more easily? +- Does it help Susan consume automations more easily? +- Is this something that is coding specific? diff --git a/README.md b/README.md index c1df8156c..7ef434ff1 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,13 @@ OpenWork is designed around the idea that you can easily ship your agentic workf ## Quick start -Download the correct version in [here](https://openworklabs.com/download), in the latest [releases](https://github.com/different-ai/openwork/releases) or install from source below. +Download the desktop app from [openworklabs.com/download](https://openworklabs.com/download), grab the latest [GitHub release](https://github.com/different-ai/openwork/releases), or install from source below. + +- macOS and Linux downloads are available directly. +- Windows access is currently handled through the paid support plan on [openworklabs.com/pricing#windows-support](https://openworklabs.com/pricing#windows-support). +- Hosted OpenWork Cloud workers are launched from the web app after org setup, including checkout when billing is required, then connected from the desktop app via `Add a worker` -> `Connect remote`. +- OpenWork Cloud org dashboards now include shared team management and skill hub management so admins can decide who can access each published skill library before workers are launched. +- Signed-in desktop users can now browse their org's managed cloud skills directly from the Skills page and install them into the current workspace without copying files by hand. ## Why @@ -44,10 +50,12 @@ OpenWork is designed to be: - **Execution plan**: render OpenCode todos as a timeline. - **Permissions**: surface permission requests and reply (allow once / always / deny). - **Templates**: save and re-run common workflows (stored locally). +- **Debug exports**: copy or export the runtime debug report and developer log stream from Settings -> Debug when you need to file a bug. - **Skills manager**: - list installed `.opencode/skills` folders - - install from OpenPackage (`opkg install ...`) - import a local skill folder into `.opencode/skills/` + - browse OpenWork Cloud team skills from your active org and install them into the current workspace + - share an installed skill either as a public link or to an org-managed skill hub ## Skill Manager @@ -144,14 +152,6 @@ Capability permissions are defined in: - `apps/desktop/src-tauri/capabilities/default.json` -## OpenPackage Notes - -If `opkg` is not installed globally, OpenWork falls back to: - -```bash -pnpm dlx opkg install -``` - ## OpenCode Plugins Plugins are the **native** way to extend OpenCode. OpenWork now manages them from the Skills tab by @@ -182,6 +182,8 @@ pnpm test:e2e ## Troubleshooting +If you need to report a desktop or session bug, open Settings -> Debug and export both the runtime debug report and developer logs before filing an issue. + ### Linux / Wayland (Hyprland) If OpenWork crashes on launch with WebKitGTK errors like `Failed to create GBM buffer`, disable dmabuf or compositing before launch. Try one of the following environment flags. diff --git a/SUPPORT.md b/SUPPORT.md index d5b816020..37b51dd6e 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -13,7 +13,10 @@ Use the right channel to get faster help: - Search existing issues to avoid duplicates. - Include exact OpenWork/OpenCode versions, OS, and reproduction steps. -- Add logs/screenshots when possible. +- For desktop, worker, or session bugs, open Settings -> Debug and include both: + - the runtime debug report + - the developer log export +- Add screenshots when they help explain the flow or failure state. ## Maintainer triage diff --git a/VISION.md b/VISION.md index 817d5524c..39103d51c 100644 --- a/VISION.md +++ b/VISION.md @@ -20,8 +20,9 @@ Current cloud mental model: OpenWork helps users ship agentic workflows to their team. It works on top of opencode (opencode.ai) an agentic coding platform that exposes apis and sdks. We care about maximally using the opencode primitives. And build the thinest possible layer - always favoring opencode apis over custom built ones. In other words: + - OpenCode is the **engine**. -- OpenWork is the **experience** : onboarding, safety, permissions, progress, artifacts, and a premium-feeling UI. +- OpenWork is the **experience** : workspace setup, remote connect, safety, permissions, progress, artifacts, and a premium-feeling UI. OpenWork competes directly with Anthropic's Cowork conceptually, but stays open, local-first, and standards-based. diff --git a/apps/orchestrator/README.md b/apps/orchestrator/README.md index 66cb1a6d0..97fb0b6c3 100644 --- a/apps/orchestrator/README.md +++ b/apps/orchestrator/README.md @@ -69,10 +69,10 @@ pnpm --filter openwork-orchestrator dev -- \ When `OPENWORK_DEV_MODE=1` is set, orchestrator uses an isolated OpenCode dev state for config, auth, data, cache, and state. OpenWork's repo-level `pnpm dev` commands enable this automatically so local development does not reuse your personal OpenCode environment. -The command prints pairing details (OpenWork server URL + token, OpenCode URL + auth) so remote OpenWork clients can connect. +The command prints pairing URLs by default and keeps live credentials out of stdout so they do not leak into shell history or collected logs. Use `--json` only when you explicitly need the raw pairing secrets in command output. Use `--detach` to keep services running and exit the dashboard. The detach summary includes the -OpenWork URL, tokens, and the `opencode attach` command. +OpenWork URL and a redacted `opencode attach` command while keeping the live tokens out of the summary. ## Sandbox mode (Docker / Apple container) diff --git a/ee/apps/den-api/README.md b/ee/apps/den-api/README.md new file mode 100644 index 000000000..eaba75e5a --- /dev/null +++ b/ee/apps/den-api/README.md @@ -0,0 +1,42 @@ +# Den API + +Hono-based Den control plane implementation (`den-api`, formerly `den-controller`). + +This package is the active Den control plane implementation. + +It carries the full migrated Den API route surface in a foldered Hono structure so agents can navigate one area at a time without scanning the whole service. + +## Quick start + +```bash +pnpm --filter @openwork-ee/den-api dev:local +``` + +## Current routes + +- `GET /` -> `302 https://openworklabs.com` +- `GET /health` +- Better Auth mount at `/api/auth/*` +- desktop handoff routes under `/v1/auth/*` +- current user routes under `/v1/me*` +- organization routes under `/v1/orgs*`, including org setup, invitations, members, roles, teams, and shared skill hub management +- admin routes under `/v1/admin*` +- worker lifecycle and billing routes under `/v1/workers*`, including checkout redirects and org limit enforcement + +## Folder map + +- `src/routes/auth/`: Better Auth mount + desktop handoff endpoints +- `src/routes/me/`: current user and current user's org resolution routes +- `src/routes/org/`: organization CRUD-ish surfaces, split by area +- `src/routes/admin/`: admin-only reporting endpoints +- `src/routes/workers/`: worker lifecycle, billing, runtime, and heartbeat endpoints +- `src/middleware/`: reusable Hono middleware for auth context, org context, teams, and validation + +Each major folder also has its own `README.md` so future agents can inspect one area in isolation. + +## Migration approach + +1. Keep `den-api` (formerly `den-controller`) as the source of truth for Den control-plane behavior. +2. Add endpoints in focused Hono route groups one surface at a time. +3. Reuse shared middleware and Zod validators instead of duplicating request/session/org plumbing. +4. Leave a short README in each route area when the structure changes so later agents can recover context fast. diff --git a/ee/apps/den-web/README.md b/ee/apps/den-web/README.md index f66b4720f..bd906e81c 100644 --- a/ee/apps/den-web/README.md +++ b/ee/apps/den-web/README.md @@ -1,14 +1,29 @@ # OpenWork Cloud App (`ee/apps/den-web`) -Frontend for `app.openwork.software`. +Frontend for `app.openworklabs.com`. ## What it does - Signs up / signs in users against Den service auth. +- Handles invited-org signup flows where the invited email stays locked and the user verifies access before joining. +- Lets org admins manage members, teams, roles, invitations, and shared skill hubs from the hosted dashboard. +- Saves pending org-creation drafts across checkout so a user can finish setup without re-entering the org name after billing. - Launches cloud workers via `POST /v1/workers`. -- Handles paywall responses (`402 payment_required`) and shows Polar checkout links. -- Uses a Next.js proxy route (`/api/den/*`) to reach `api.openwork.software` without browser CORS issues. -- Uses a same-origin auth proxy (`/api/auth/*`) so GitHub OAuth callbacks can land on `app.openwork.software`. +- Handles paywall responses (`402 payment_required`), routes users through Polar checkout during org setup or worker launch, and only enables worker launch after purchase. +- Surfaces org limit states before launch so users know when a plan upgrade or seat change is required. +- Preserves full `SKILL.md` frontmatter and body when shared skills are saved so the desktop app sees the same title, description, and install payload that admins authored. +- Offers desktop handoff actions so users can open the generated worker directly in OpenWork or copy the connect credentials manually. +- Uses a Next.js proxy route (`/api/den/*`) to reach `api.openworklabs.com` without browser CORS issues. +- Uses a same-origin auth proxy (`/api/auth/*`) so GitHub OAuth callbacks can land on `app.openworklabs.com`. + +## Current hosted user flow + +1. Sign in with a standard provider or accept an org invite. +2. Create or join an organization; if that org requires billing, complete checkout before continuing. +3. If checkout interrupts org creation, the dashboard restores the saved org draft when the user returns. +4. Optional admin step: manage members, teams, and shared skill hubs from the org dashboard, then publish skills that appear in the desktop Skills page for signed-in org members. +5. Launch the worker from the cloud dashboard. +6. Open the worker in the desktop app with the provided deep link, or copy the URL/token into `Connect remote` manually. ## Local development @@ -22,16 +37,16 @@ Frontend for `app.openwork.software`. ### Optional env vars - `DEN_API_BASE` (server-only): upstream API base used by proxy route. - - default: `https://api.openwork.software` + - default: `https://api.openworklabs.com` - `DEN_AUTH_ORIGIN` (server-only): Origin header sent to Better Auth endpoints when the browser request does not include one. - - default: `https://app.openwork.software` + - default: `https://app.openworklabs.com` - `DEN_AUTH_FALLBACK_BASE` (server-only): fallback Den origin used if `DEN_API_BASE` serves an HTML/5xx error. - default: `https://den-control-plane-openwork.onrender.com` - `NEXT_PUBLIC_OPENWORK_APP_CONNECT_URL` (client): Base URL for "Open in App" links. - - Example: `https://openwork.software/app` + - Example: `https://openworklabs.com/app` - The web panel appends `/connect-remote` and injects worker URL/token params automatically. - `NEXT_PUBLIC_OPENWORK_AUTH_CALLBACK_URL` (client): Canonical URL used for GitHub auth callback redirects. - - default: `https://app.openwork.software` + - default: `https://app.openworklabs.com` - this host must serve `/api/auth/*`; the included proxy route does that - `NEXT_PUBLIC_POSTHOG_KEY` (client): PostHog project key used for Den analytics. - optional override; defaults to the same project key used by `ee/apps/landing` @@ -45,10 +60,12 @@ Recommended project settings: - Root directory: `ee/apps/den-web` - Framework preset: Next.js -- Build command: `next build` +- Build command: `cd ../../.. && pnpm --filter @openwork-ee/den-web build` - Output directory: `.next` -- Install command: `pnpm install --frozen-lockfile` +- Install command: `cd ../../.. && pnpm install --frozen-lockfile` + +These commands should be configured in the Vercel dashboard rather than committed in `vercel.json`, so the app still builds from the monorepo root and can resolve shared workspace packages like `@openwork-ee/utils`. Then assign custom domain: -- `app.openwork.software` +- `app.openworklabs.com` diff --git a/packages/docs/accessing-ow-from-slack.mdx b/packages/docs/accessing-ow-from-slack.mdx index fde0864a4..97cb115db 100644 --- a/packages/docs/accessing-ow-from-slack.mdx +++ b/packages/docs/accessing-ow-from-slack.mdx @@ -1,6 +1,6 @@ --- -title: "OpenWork Link: Connecting you slack with your workspace" -description: "Learn how to connect your slack with your workspace" +title: "Connecting Slack to your workspace" +description: "Learn how to connect Slack to an OpenWork workspace" --- In order to connect `slack` with your openwork `workspace`, you will need the following: @@ -15,7 +15,7 @@ This is one of the most relevant and meaningful applications of Openwork, and we ## Having the right slack permissions -You should either be a slack `owner`, `admin` or have the right level of approval to be able to add an app into slack. +You should either be a Slack `owner`, `admin`, or have the right level of approval to add an app into Slack. ## Creating a slack app @@ -42,7 +42,8 @@ Now, once you have both of these tokens, you can directly paste them into the ap ![Clean Shot 2026 03 24 At 17 15 15@2x](/images/CleanShot2026-03-24at17.15.15@2x.png) - Paste you `xorb-` and `xapp-` tokens into `Settings` \> `messaging` +Paste you `xorb-` and `xapp-` tokens into `Settings` \> `messaging` + ## Send test message @@ -50,7 +51,8 @@ Now, once you have both of these tokens, you can directly paste them into the ap Test the bot by sending a message. It should respond instantly indicating that a new session has been initiatied and then send the actual response afterwards. For now, you will have to use `@slack-bot-name` every time you want to talk to it. - ![Clean Shot 2026 03 24 At 17 16 43@2x](/images/CleanShot2026-03-24at17.16.43@2x.png) + ![Clean Shot 2026 03 24 At 17 16 + 43@2x](/images/CleanShot2026-03-24at17.16.43@2x.png) ## Template Manifest Example @@ -92,4 +94,4 @@ settings: org_deploy_enabled: false socket_mode_enabled: true token_rotation_enabled: false -``` \ No newline at end of file +``` diff --git a/packages/docs/automating-tasks.mdx b/packages/docs/automating-tasks.mdx new file mode 100644 index 000000000..dcc130508 --- /dev/null +++ b/packages/docs/automating-tasks.mdx @@ -0,0 +1,35 @@ +--- +title: "Automating tasks" +description: "Create and manage recurring jobs from Settings -> Automations" +--- + +OpenWork can turn a prompt into a recurring automation. + +You can find the feature in `Settings` -> `Automations`. + +## Before you start + +- On the desktop app, install the scheduler plugin if OpenWork asks for it. +- If OpenWork shows `Reload OpenWork to activate automations`, reload the workspace so the scheduler becomes available. +- If you are connected to a remote OpenWork server, the Automations page shows the jobs already registered on that server. + +![Automations page in Settings](/images/image-1.png) + +## Create a new automation + +1. Open `Settings` -> `Automations`. +2. Click `New automation`. +3. Give the job a name, write the prompt you want OpenWork to run, and choose the schedule. +4. Click `Prepare in chat`. + +OpenWork currently prepares the scheduler command for you in chat, so you can review it before it runs. + +![Create automation modal](/images/image-3.png) + +If the setup succeeds, OpenWork confirms the automation in chat. + +![Automation prepared successfully in chat](/images/image-4.png) + +After that, the new job appears in the Automations list, where you can refresh it, run it in chat, or remove it. + +![Saved automation listed in Settings](/images/image-5.png) diff --git a/packages/docs/computer-use.mdx b/packages/docs/computer-use.mdx index 17cf1579d..3dba85ab8 100644 --- a/packages/docs/computer-use.mdx +++ b/packages/docs/computer-use.mdx @@ -1,27 +1,28 @@ --- -title: "OpenWork Use: Controlling your browser" -description: "How to use OpenWork to automate your Chrome Browser" +title: "Controlling your browser with OpenWork" +description: "How to use OpenWork to automate Google Chrome" --- -Computer-Use in OpenWork currently works as a browser automation in Google Chrome. It does not yet mean full desktop control of Ubuntu, macOS, or Windows apps. +Computer Use in OpenWork currently works as browser automation in Google Chrome. It does not yet mean full desktop control of Ubuntu, macOS, or Windows apps. -With the right skills, your OpenWork agent will be able to runs browser actions and take screnshots as proof of having completed said actions. If you connect to a remote OpenWork server, that remote machine also needs to have Chrome installed. +With the right extension enabled, your OpenWork agent can run browser actions and take screenshots as proof of completion. If you connect to a remote OpenWork server, that remote machine also needs Chrome installed. Today, the supported path is `Control Chrome`, which uses Chrome DevTools MCP. ## Requirements - Google Chrome on the machine running the session -- In `Settings > Extensions > Control Chrome` +- `Settings` -> `Extensions` -> `Control Chrome` - ![Screenshot 2026 03 25 At 11 47 52](/images/Screenshot2026-03-25at11.47.52.png) + ![Control Chrome extension in + Settings](/images/Screenshot2026-03-25at11.47.52.png) + - - Enable it and follow the instructions in the configuration screen _Note_: _do note use "Use my existing Chrome profile". It's currently not well supported._ - - ![Image](/images/image.png) - - Go back to the session view and ask it to open a website +Enable `Control Chrome`, then follow the setup steps from the configuration screen. - ![Image](/images/image-1.png) - \ No newline at end of file +![Control Chrome setup instructions](/images/image.png) + +Avoid `Use my existing Chrome profile` for now; the isolated profile flow is more reliable. + +Once setup is complete, go back to a session and ask OpenWork to open a website or complete a browser task. diff --git a/packages/docs/docs.json b/packages/docs/docs.json index 305bede68..08d3bbfdd 100644 --- a/packages/docs/docs.json +++ b/packages/docs/docs.json @@ -19,22 +19,23 @@ "pages": [ "get-started", { - "group": "Tutorials", + "group": "Desktop App", "pages": [ - "sharing-ow-setup", - "how-to-connect-a-custom-provider", + "how-to-connect-chat-gpt", "how-to-connect-mcps", - "accessing-ow-from-slack", - "importing-a-skill", "computer-use", - "how-to-connect-chat-gpt" + "automating-tasks", + "sharing-ow-setup", + "accessing-ow-from-slack" ] }, + { + "group": "Tutorials", + "pages": ["how-to-connect-a-custom-provider", "importing-a-skill"] + }, { "group": "Improve this doc", - "pages": [ - "missing-docs" - ] + "pages": ["missing-docs"] } ] } diff --git a/packages/docs/get-started.mdx b/packages/docs/get-started.mdx index e7ea7312f..146df6438 100644 --- a/packages/docs/get-started.mdx +++ b/packages/docs/get-started.mdx @@ -22,28 +22,32 @@ openwork start --workspace /path/to/your/workspace --approval auto ``` - ![OpenWork CLI terminal output showing URL and owner token](/images/get-started-cli-output.png) + ![OpenWork CLI terminal output showing the connect URL and owner token](/images/get-started-cli-output.png) Copy: - `OpenWork URL` -- `OpenWork Owner Token` +- `OpenWork owner token` ## Step 3: Connect the OpenWork desktop app On your local machine, open the OpenWork desktop app and connect into a remote workspace with: -- On the bottom left click `+ Add workspace` -- Then click `+ Connect Remote workspace` -- Type in the `OpenWork URL and OpenWork Owner Token` from earlier +- On the bottom left click `+ Add a worker` +- Then click `Connect remote` +- Paste in the `OpenWork URL` and the token from earlier + +The connect form accepts a collaborator token or an owner token. If you started the worker yourself with `openwork start`, the token shown in the terminal is the owner token and works for this flow. ![Add Remote Workspace dialog in OpenWork desktop app](/images/get-started-add-remote-workspace.png) +If you launched the worker from OpenWork Cloud, `Open in OpenWork` can prefill that remote-connect flow for you. The manual fallback is still the same `Add a worker` -> `Connect remote` path with the worker URL and token. + ## What this gives you right away - Your code and services stay on the remote machine. - Your local machine stays light. -- You get a fast path from install to a connected remote OpenWork workspace. \ No newline at end of file +- You get a fast path from install to a connected remote OpenWork workspace. diff --git a/packages/docs/how-to-connect-chat-gpt.mdx b/packages/docs/how-to-connect-chat-gpt.mdx index 0a8eb2bc5..0258c8226 100644 --- a/packages/docs/how-to-connect-chat-gpt.mdx +++ b/packages/docs/how-to-connect-chat-gpt.mdx @@ -17,7 +17,11 @@ Then, login into `openai Auth` with a valid subscription email ![OpenAI authentication login page](/images/chatgpt-openai-auth-login.png) -Once you have finished the auth, you can change the model below in the chat. +Once you have finished the auth, open `Settings` -> `Default model` if you want new chats in that workspace to keep using ChatGPT by default. + +If the model supports reasoning profiles, configure that on the model card before closing the picker. OpenWork now keeps those default-model changes instead of dropping them on refresh. + +You can still switch the model for a single chat from the picker in the chat view. ![Model selector dropdown in chat](/images/chatgpt-model-selector.png) @@ -27,4 +31,4 @@ You will be able to choose among any model offered by all the providers you're c ![Model list showing available models from all providers](/images/chatgpt-model-list.png) - \ No newline at end of file + diff --git a/packages/docs/images/image-1.png b/packages/docs/images/image-1.png index 24d6bc43c..a07d2834f 100644 Binary files a/packages/docs/images/image-1.png and b/packages/docs/images/image-1.png differ diff --git a/packages/docs/images/image-3.png b/packages/docs/images/image-3.png new file mode 100644 index 000000000..557b4306a Binary files /dev/null and b/packages/docs/images/image-3.png differ diff --git a/packages/docs/images/image-4.png b/packages/docs/images/image-4.png new file mode 100644 index 000000000..144c57c57 Binary files /dev/null and b/packages/docs/images/image-4.png differ diff --git a/packages/docs/images/image-5.png b/packages/docs/images/image-5.png new file mode 100644 index 000000000..54e48b7ce Binary files /dev/null and b/packages/docs/images/image-5.png differ diff --git a/packages/docs/importing-a-skill.mdx b/packages/docs/importing-a-skill.mdx index 6ace7277f..a05669a5c 100644 --- a/packages/docs/importing-a-skill.mdx +++ b/packages/docs/importing-a-skill.mdx @@ -1,53 +1,53 @@ --- title: "Importing a skill" -description: "How to import an external skill to your workspace in Openwork" +description: "How to import an external skill into your workspace in OpenWork" --- There are currently three direct ways to import an external skill. -1. Importing an existing skill with share.openworklabs -2. Pasting a skill in share.openworklabs, then importing it. -3. Creating a skill using `Create skill in chat` and pasting the external skill +1. Open an existing skill share link from `share.openwork.software` +2. Paste a skill into the share site, then import it +3. Create a skill with `Create skill in chat` and paste the external skill into that flow -There is another option if you're technical which is pasting it into the `workspace/skills` folder. +There is another option if you're technical: place it directly in `.opencode/skills//SKILL.md` inside your workspace. -We recommend using (1) and (3) as they're the options more directly compatible and easy to use. +We recommend (1) and (3) because they match the built-in OpenWork flows most closely. ## Importing an existing skill with a share URL -When you have an openwork [Share URL](https://share.openwork.software/b/01KKPSGYSGDRRWNTAACAMZY3PF), you just need to click `Open in Openwork` +When you have an OpenWork [share URL](https://share.openwork.software/b/01KKPSGYSGDRRWNTAACAMZY3PF), click `Open in OpenWork`. ![Share page with Open in OpenWork button](/images/skill-import-share-page.png) -Then, select the workspace in which you'd like to import it into (eg: in this case, `the-factory`). +Then select the workspace where you want to install it (for example, `the-factory`). ![Select workspace dialog for importing a skill](/images/skill-import-select-workspace.png) -Once this is installed, Openwork will prompt you to reload so that it can load the skill into your workspace. +Once the skill is installed, OpenWork prompts you to reload so it can load the new skill into your workspace. ![Reload required banner after installing a skill](/images/skill-import-reload-required.png) -Once you've reloaded the app, you should be able to use it directly into your workspace: +After you reload the app, you can use the skill directly in that workspace: ![Using an imported skill in chat with autocomplete](/images/skill-import-use-in-chat.png) -## Pasting a skill in share.openworklabs, then importing it. +## Pasting a skill into the share site, then importing it -In this case, you start at [the skills share page](https://share.openwork.software/) without any skill. Paste or upload the skill there, and click on generate link: +Start at [the OpenWork share page](https://share.openwork.software/) without any skill loaded. Paste or upload the skill there, then click `Generate link`: ![Share your skill page with Generate share link button](/images/skill-import-share-your-skill.png) -**Note**: In order to import an external skill, the skill needs to adhere to the following structure: +To import an external skill, the file needs to follow this structure: ```text --- @@ -58,17 +58,14 @@ description: one line description of what the skill does Any markdown text with instructions and description of the skill ``` -Make sure it follows this format when importing external skills from other marketplaces +Make sure the file follows that format when importing skills from other marketplaces or other teams. -This then redirects you to the `Share Page` of a valid skill, and you can follow the steps from the previous section directly. +That redirects you to the share page for the valid skill, and from there you can follow the steps from the previous section. -## Creating a skill using `/skill-creator` in the chat +## Creating a skill with `/skill-creator` in chat -This option is quite straightforward, you can type `/skill-creator` in the chatand either directly paste the external skill you're seeking to import or describe what you'd like for the skill to do -and then, it will proceed to generate it. +Type `/skill-creator` in chat, then either paste the external skill you want to import or describe what you want the skill to do. OpenWork will generate a workspace-local skill from that input. ![Using the /skill-creator command in chat](/images/skill-import-skill-creator-command.png) - - - \ No newline at end of file diff --git a/packages/docs/sharing-ow-setup.mdx b/packages/docs/sharing-ow-setup.mdx index 13da44423..f70de1a34 100644 --- a/packages/docs/sharing-ow-setup.mdx +++ b/packages/docs/sharing-ow-setup.mdx @@ -1,40 +1,93 @@ --- title: "OpenWork Templates: How to share your setup" -description: "Learn how to share your MCP, agents, skills with others" +description: "Learn how to share a full workspace template or a single skill in OpenWork" --- -There are two main primitives for a template that you can share: `Workspace` and a -`Skill`. +There are two main things you can share from OpenWork: + +- a full `Workspace` template +- a single `Skill` ## Sharing your entire configuration -OpenWork also allows you to share your entire configuration with others. That includes skills, MCPs, agents, unique LLM providers you might've added, and more. +OpenWork can package an entire workspace template into one share link. That bundle can include your skills, commands, agents, MCP/OpenCode settings, `opencode.json` state, and other shareable `.opencode/**` files. +OpenWork does not copy secrets, runtime-only files, or your existing session history into the template. If OpenWork detects secret-like provider settings, plugin config, MCP credentials, or portable files that look sensitive, it warns and excludes that data from the exported template. -Click on the `...` next to the workspace name, then `Share ...` , then `Share a template` +Click the `...` next to the workspace name, then `Share...`, then `Share a template`. - ![Share workspace dialog with template and remote options](/images/sharing-workspace-template-dialog.png) + ![Share workspace dialog with template and remote + options](/images/sharing-workspace-template-dialog.png) +When someone opens that link and clicks `Open in OpenWork`, OpenWork now creates a new workspace from the template instead of dropping the bundle into the current workspace. + +OpenWork asks the recipient to pick a destination folder first, then creates the workspace there from the shared template. + +Some templates can also include starter sessions. Those starter sessions are seeded into the new workspace on first load so the recipient gets the intended prompts and example setup, but OpenWork does not clone the original runtime chat history. + +This makes workspace templates a good fit for sharing: + +- complete project setup +- reusable MCP and provider configuration +- commands, agents, and skills that should travel together +- example starter flows for a new workspace + +## Accessing a live workspace remotely + +The same `Share...` menu also includes `Access workspace remotely` for the running workspace itself. + +That flow is different from a template link: + +- a template creates a reusable copy someone can import into a new workspace +- remote access reveals live connection details for the current running workspace + +Remote access is off by default. Turn it on only when you want this worker reachable from another machine, then click `Save` so OpenWork can restart the worker and reveal the current connection details. + +OpenWork can show: + +- the worker URL to paste into `Add a worker` -> `Connect remote` +- an owner/access token for full control +- an optional collaborator token for routine access without permission approvals + +Treat those credentials like passwords. Anyone who has them can connect to the live workspace. + +## Sharing a template with your Cloud team + +OpenWork can also save a workspace template directly to your active OpenWork Cloud organization. + +Open the same `Share a template` flow, then choose `Share with team`. + +From there you can: + +- pick the template name your teammates will see +- save it to the currently selected Cloud organization +- sign in to OpenWork Cloud first if the app prompts you to + +Team templates do not create a public share URL. Instead, they show up in the OpenWork Cloud area inside the app so other members of that organization can open them later. + +After sign-in, teammates can open the template from `Settings` -> `OpenWork Cloud` -> `Team templates`. ## How to share a SKILL.md -You can share a `SKILL.md` by clicking under `Your_Workspace` \> `Skills` +You can share a `SKILL.md` from `Your_Workspace` > `Skills`. - ![Skills management page showing installed skills](/images/sharing-skills-list.png) + ![Skills management page showing installed + skills](/images/sharing-skills-list.png) -Then, on `Create Link` which will create a custom page for the skill at `share.openwork.software/b/:skill_id` +Click `Create Link` to generate a custom share page for that skill at `share.openwork.software/b/:skill_id`. - ![Create share link dialog for a skill](/images/sharing-create-link-dialog.png) + ![Create share link dialog for a + skill](/images/sharing-create-link-dialog.png) -This creates a url that you can share with other people so they can `copy the skill` or `Open in Openwork` +That creates a URL you can send to other people so they can `Copy the skill` or `Open in OpenWork`. - ![Shared skill page with Copy and Open in OpenWork buttons](/images/sharing-skill-share-page.png) + ![Shared skill page with Copy and Open in OpenWork + buttons](/images/sharing-skill-share-page.png) - diff --git a/packaging/aur/README.md b/packaging/aur/README.md index d768520d6..d3d99a940 100644 --- a/packaging/aur/README.md +++ b/packaging/aur/README.md @@ -1,12 +1,13 @@ -# Arch Linux AMD64 package +# Arch Linux package -Use this directory to build and install the AMD64 OpenWork package locally on Arch Linux without Docker. +Use this directory to build and install the OpenWork package locally on Arch Linux without Docker. ## What this packaging does - Targets `x86_64` Arch Linux. - Downloads the published GitHub release asset `openwork-desktop-linux-amd64.deb`. - Repackages the `.deb` contents into an Arch package with `makepkg`. +- Removes the bundled `/usr/bin/opencode` file so the package does not conflict with `opencode-bin`. ## Prerequisites @@ -36,6 +37,14 @@ That will: 2. build an Arch package such as `openwork--1-x86_64.pkg.tar.zst` 3. install it locally with `pacman` +After install, `openwork` is available as the desktop launcher. If you also want the standalone OpenCode CLI, install `opencode-bin` separately. + +## OpenCode CLI conflict note + +Recent `.deb` builds include `/usr/bin/opencode`, but the AUR package intentionally strips that file during repackaging. + +That keeps OpenWork compatible with systems that already install the OpenCode CLI from `opencode-bin`, which should remain the owner of the global `opencode` command. + ## Update the package to a newer release If the GitHub release version changed, refresh the packaging metadata first: