2026-09-02 01:05:41 +08:00
commit 04bac1f6e2
2200 changed files with 489415 additions and 0 deletions
@@ -0,0 +1,37 @@
---
title: "Collections"
description: "Group plugins into reusable Cloud assignments for teams and members"
---
Collections are the advanced OpenWork Cloud tool for grouping multiple plugins and assigning them as one managed set. Use a Collection when the same team or members need several plugins, when you expect the set to change, or when individual plugin grants would become difficult to maintain.
For the simplest one-skill publishing flow, start with [Publish and copy a skill](/start-here/do-work-with-it/publish-and-copy-a-skill).
## How Collections work
- A plugin contains skills and can also contain other extension resources.
- A Collection contains one or more plugins.
- A Collection can be granted to everyone in the organization, selected teams, or individual members.
- The plugin creator keeps access automatically.
- Adding, updating, or removing a plugin changes the managed set for the Collection's audience. Members can use `Refresh` in `Settings > Library` if a recent change has not appeared yet.
## Create and assign a Collection
1. Open `Collections` in the OpenWork Cloud dashboard.
2. Click `New collection`, enter a clear name and optional description, then click `Create collection`.
3. Open `Plugin Directory` and create or edit each plugin that belongs in the Collection.
4. In each plugin's `Share` section, choose the Collection.
5. Return to the Collection and use `Who can access this` to add teams or individual members, or turn on access for everyone in the organization.
6. Ask a member to open `Settings > Library` in the desktop app and confirm the assigned plugins and skills are present.
Only owners and admins can create Collections and publish skills for other people by default.
## Keep complex setups manageable
- Create Collections around a stable audience or purpose, such as `Sales Enablement` or `Engineering Operations`.
- Put plugins used by the same audience in one Collection so one access change covers the whole set.
- Prefer team grants over many individual grants when membership changes often.
- Use separate Collections when audiences or update schedules differ.
- Review Collection access before adding a plugin that reaches sensitive systems.
For a complete organization walkthrough, see [Team quickstart](/cloud/team-quickstart). For managed service accounts and MCP servers, use [Connectors](/cloud/share-with-your-team/shared-mcp-connections) rather than placing credentials in a skill.
@@ -0,0 +1,137 @@
---
title: "Adding a custom LLM provider"
description: "Create a custom provider definition in OpenWork Cloud and import it into the desktop app"
---
Use this when the provider is not in the catalog. The Cloud dashboard stores the shared credential once and then lets desktop workspaces import it.
<Frame>
  ![Custom LLM provider detail in OpenWork Cloud](/images/cloud-custom-llm-provider-detail.png)
</Frame>
## Create the custom provider
1. Open `LLM Providers`.
2. Click `Add Provider`.
3. Switch to `Custom provider`.
4. Give it a `Name` (the `Provider ID` fills in automatically).
5. Enter the `Base URL` of the OpenAI-compatible endpoint (for Azure AI Foundry this looks like `https://my-resource.openai.azure.com/openai/v1`).
6. List the `Model IDs` the endpoint serves — on Azure AI Foundry these are your deployment names.
7. Paste the shared `API key / credential`.
8. Choose `People access` and/or `Team access`.
9. Click `Create Provider`.
That's it — no JSON required for OpenAI-compatible endpoints.
### Advanced: raw JSON config
If the provider needs more than the form covers (a different AI SDK package, per-model limits or modalities, custom options), click `Advanced: edit as JSON` and provide a models.dev-style definition. The JSON must include `id`, `name`, `npm`, `env`, and `models`; `api` is optional, but most OpenAI-compatible providers use it. The editor requires valid JSON, at least one environment variable, and at least one model.
```json
{
  "id": "custom-provider",
  "name": "Custom Provider",
  "npm": "@ai-sdk/openai-compatible",
  "env": [
    "CUSTOM_PROVIDER_API_KEY"
  ],
  "doc": "https://example.com/docs/models",
  "api": "https://api.example.com/v1",
  "models": [
    {
      "id": "custom-provider/example-model",
      "name": "Example Model",
      "attachment": false,
      "reasoning": false,
      "tool_call": true,
      "structured_output": true,
      "temperature": true,
      "release_date": "2026-01-01",
      "last_updated": "2026-01-01",
      "open_weights": false,
      "limit": {
        "context": 128000,
        "input": 128000,
        "output": 8192
      },
      "modalities": {
        "input": [
          "text"
        ],
        "output": [
          "text"
        ]
      }
    }
  ]
}
```
## Import it into the desktop app
1. Open `Settings > Cloud Providers`.
2. Choose the correct `Active org`.
3. Under `Cloud providers`, click `Import`.
4. Reload the workspace when OpenWork asks.
### Functional example: an LLM gateway (Infron)
An LLM gateway is one OpenAI-compatible endpoint that fans out to many model providers. If you want to run the routing yourself, [LiteLLM](https://infron.ai/docs/frameworks-and-integrations/litellm) is a good starting point. [Infron](https://infron.ai) is the hosted option: one API key gets you every model in its [marketplace](https://infron.ai/models) with automatic provider fallbacks and a single invoice, so adding a new LLM to OpenWork is just another entry under `models`.
Grab a key from the [API Keys dashboard](https://infron.ai/dashboard/apiKeys). If you don't have an account yet, sign up at [infron.ai/login](https://infron.ai/login) and their [quickstart](https://infron.ai/docs/overview/quickstart/text) walks you through your first request.
Paste the key into `API key / credential` and use this JSON:
```json
{
  "id": "infron",
  "name": "Infron",
  "npm": "@ai-sdk/openai-compatible",
  "env": [
    "INFRON_API_KEY"
  ],
  "doc": "https://infron.ai/docs/frameworks-and-integrations/openwork",
  "api": "https://llm.onerouter.pro/v1",
  "models": [
    {
      "id": "deepseek/deepseek-v3.2",
      "name": "DeepSeek V3.2",
      "attachment": false,
      "reasoning": true,
      "tool_call": true,
      "structured_output": true,
      "temperature": true,
      "release_date": "2025-09-29",
      "last_updated": "2025-09-29",
      "open_weights": true,
      "limit": {
        "context": 128000,
        "input": 128000,
        "output": 8192
      },
      "modalities": {
        "input": ["text"],
        "output": ["text"]
      }
    }
  ]
}
```
Once imported, Infron models show up in the Chat model picker alongside everything else:
<Frame>
  ![DeepSeek V3.2 via Infron in the OpenWork Chat model picker](/images/infron-model-picker.png)
</Frame>
Pick the model and it's live in the session footer:
<Frame>
  ![Infron · DeepSeek V3.2 selected in an OpenWork session](/images/infron-model-active.png)
</Frame>
Add more entries under `models` to expose other routes the gateway supports (e.g. `openai/gpt-5.4`, `google/gemini-2.5-flash`).
## When to use a cloud provider
Use a Cloud provider when the setup is meant to be shared across an org or team. For solo use, configuring it directly in the desktop app is simpler.
@@ -0,0 +1,29 @@
---
title: "Desktop policies"
description: "Use OpenWork Cloud to control desktop app capabilities for members and teams."
---
Desktop policies let organization owners and admins manage what the OpenWork desktop app allows after a member signs in to Cloud. Policies can apply to the whole organization through the default policy, or to specific members and teams through assigned policies. Policies can also provide [team prompt cards](/cloud/share-with-your-team/team-prompt-cards). The desktop app caches the effective policy, applies it on reload, and refreshes it when the active Cloud organization changes, the Cloud account changes, or the hourly desktop-config refresh runs.
## What policies control
Current desktop policy keys map to concrete product capabilities:
- `Custom providers`: allow or block locally added model providers that were not deployed through OpenWork Cloud.
- `Enable OpenCode Zen Models`: allow or block built-in OpenCode models.
- `Multiple workspaces`: allow or block creating or configuring more than one local workspace.
- `Control Settings`: allow or block changing desktop settings.
- `Manage Extensions`: allow or block local extension management.
- `Built-in Extensions`: allow or block OpenWork-provided built-in extensions, including browser, image, and local-provider extensions.
- `Welcome Page`: show or hide the getting-started page for new users.
## Configure a policy
1. Open [app.openworklabs.com](https://app.openworklabs.com/) and choose your organization.
2. Go to `Desktop policies`.
3. Create a new policy or edit the default policy.
4. Turn capabilities on or off.
5. Assign the policy to members or teams when it should not apply to everyone.
6. Save the policy, then have members reload, refresh their Cloud account, switch the active organization, or wait for the hourly desktop-config refresh.
The desktop app explains blocked capabilities as organization-controlled. For example, a built-in extension disabled by policy is hidden from the normal catalog and can appear in hidden views with a `Disabled by organization` explanation.
@@ -0,0 +1,40 @@
---
title: "Adding a managed LLM provider"
description: "Create an org-managed provider in OpenWork Cloud and import it into the desktop app"
---
Use `Models > Bring your Own Keys` when you want the organization to manage the credential, model list, and access rules once, then make the provider available to desktop workspaces.
## Create the provider in OpenWork Cloud
1. Open `Models > Bring your Own Keys`.
2. Click `Add Provider`.
3. Stay on `Catalog provider`.
4. Choose the provider in `Provider`.
5. Select the models the org should expose.
6. Paste the shared `API key / credential`.
7. Choose `People access` and/or `Team access`.
8. Click `Create Provider`.
<Frame>
  ![Managed LLM provider detail in OpenWork Cloud](/images/cloud-managed-llm-provider-detail.png)
</Frame>
## Import it into the desktop app
1. Open `Settings > Cloud Providers`.
2. Choose the correct `Active org`.
3. Under `Cloud providers`, click `Import`.
4. Reload the workspace when OpenWork asks.
OpenWork writes the imported provider into the workspace `opencode.jsonc` and stores the org credential for that workspace.
## Update or remove it later
- Use `Sync` after changing models or access in OpenWork Cloud.
- Use `Remove` to stop managing the imported provider from this workspace.
- If the provider was deleted in Cloud, the desktop app shows `Removed from cloud` and lets you `Uninstall` the local config.
- The provider must have a stored org credential before the desktop app can import it.
If you only need a one-off local setup, use the desktop guide at [Adding a custom LLM provider/model](/start-here/connect-your-stack/add-a-custom-llm).
@@ -0,0 +1,128 @@
---
title: "Per-member LLM credentials"
description: "Bind a separate write-only provider credential to each organization member"
---
Per-member credential bindings let an organization grant one managed LLM provider to many people without sharing one upstream key. Use this when an external gateway, such as LiteLLM, issues a distinct virtual key for each member.
This page describes an API integration pattern. LiteLLM provisioning and metadata discovery are not built into Den; run your own provisioner against Den's generic provider and credential-binding routes plus the LiteLLM API.
## Choose a credential mode
Set `credentialMode` when you create or update an organization LLM provider:
- `shared` stores one provider credential. Every granted member receives that credential from the connect route.
- `per_member` resolves a separate binding for the calling organization member. The provider can be granted before a binding exists.
Create a per-member custom provider with `POST /v1/llm-providers`:
```json
{
  "name": "Per-member gateway",
  "source": "custom",
  "customConfig": {
    "id": "per-member-gateway",
    "name": "Per-member gateway",
    "npm": "@ai-sdk/openai-compatible",
    "env": ["GATEWAY_API_KEY"],
    "api": "https://gateway.example.com/v1",
    "models": [{ "id": "team-model", "name": "Team model" }]
  },
  "credentialMode": "per_member",
  "allMembers": true
}
```
Send the organization bearer token and `x-openwork-org-id` header on these requests.
## Member flow
A granted member can manage only their own write-only material:
- `PUT /v1/llm-providers/:id/my-credential` with exactly one of `{ "apiKey": "..." }` or `{ "apiKeys": { "ENV_NAME": "..." } }`
- `DELETE /v1/llm-providers/:id/my-credential`
- `GET /v1/llm-providers/:id/connect` to obtain the provider configuration and their resolved credential
The connect route always returns HTTP `200` for a granted member. When the member has no active binding, it keeps the standard provider payload shape, leaves both credential fields null, and reports the member-specific state:
```json
{
  "llmProvider": {
    "apiKey": null,
    "apiKeys": null,
    "memberCredential": { "state": "missing" }
  }
}
```
`memberCredential.state` is one of `missing`, `active`, `blocked`, `stale`, or `error`. An active response carries that member's resolved `apiKey` or `apiKeys`; every other state carries null credentials. The missing or blocked state is payload data rather than an error status because published desktop clients fail the whole provider sync on any non-OK connect response. Older clients already degrade safely by skipping a provider whose connect payload has no usable credential.
## Admin and provisioner flow
Organization owners and admins can operate a central provisioner with these routes:
- `GET /v1/llm-providers/:id/member-credentials` lists every granted membership's state, version, and external identifiers. It never returns credential material.
- `PUT /v1/llm-providers/:id/member-credentials/:orgMembershipId` stores one member's credential. The body accepts `apiKey` or `apiKeys`, plus optional `externalPrincipalId`, `externalCredentialId`, and `expectedVersion`.
- `POST /v1/llm-providers/:id/member-credentials/:orgMembershipId/block` marks an existing binding blocked.
Use `expectedVersion` when multiple provisioner workers may update the same binding. A mismatch returns HTTP `409` with `{ "error": "version_conflict" }`.
A blocked binding is admin-owned. A member cannot overwrite or delete it: member writes and deletes return HTTP `409` with `{ "error": "credential_blocked" }`. An admin `PUT` is the explicit unblock and replacement path.
## LiteLLM example
The runnable example at [`examples/litellm-per-member-keys`](https://github.com/different-ai/openwork/tree/dev/examples/litellm-per-member-keys) uses LiteLLM virtual keys. Configure the Den and LiteLLM URLs, admin tokens, provider ID, and model IDs listed in its README, then run:
```bash
node provision.mjs reconcile
```
The example first reads the exact provider from `GET /v1/llm-providers?scope=manageable`, verifies that it is a custom `per_member` provider, then queries LiteLLM `GET /model_group/info` with the master key. Every configured model must have an exact `model_group` match and finite, positive `max_input_tokens` and `max_output_tokens`. The provisioner uses those facts to update each Den model's context, input, and output limits. When present, it maps LiteLLM's function-calling, reasoning, vision, response-schema, and temperature facts to `tool_call`, `reasoning`, `attachment`, `structured_output`, and `temperature`. The replacement preserves the complete provider config, existing model fields, credential mode, and all member/team access.
This step fails closed before key creation if metadata or limits are missing. It never guesses a token limit or falls back to a generic value. The full-replacement Den PATCH omits `apiKey` and `apiKeys`, so Den preserves the write-only stored credential, and the example skips the PATCH entirely when the provider is already synchronized.
It then reconciles missing member credentials:
```js
const { memberCredentials } = await den.get(
  `/v1/llm-providers/${providerId}/member-credentials`,
)
for (const binding of memberCredentials) {
  if (binding.state !== "missing") continue
  const keyAlias = `openwork-${binding.orgMembershipId}`
  const minted = await liteLlm.post("/key/generate", {
    models,
    key_alias: keyAlias,
    metadata: {
      openwork_org_membership_id: binding.orgMembershipId,
    },
  })
  await den.put(
    `/v1/llm-providers/${providerId}/member-credentials/${binding.orgMembershipId}`,
    {
      apiKey: minted.key,
      externalCredentialId: minted.token_id,
    },
  )
}
```
LiteLLM v1.97 returns a `token_id` that can address the virtual key without retaining its plaintext value. The example stores that identifier in `externalCredentialId`; Den's admin list can return it safely to the provisioner later.
The `/model_group/info` call and field mapping are deliberately implemented in this LiteLLM-specific example. Den core remains vendor-neutral: its provider PATCH and per-member credential APIs accept the resulting generic model configuration without hardcoding LiteLLM behavior.
### Offboard in the safe order
Always revoke or block the upstream credential **before** removing its local materialization. If the upstream call fails, leave the Den binding active so the failure remains visible and retryable rather than reporting a false local block.
For the example:
1. Read the member's `externalCredentialId` from `GET /v1/llm-providers/:id/member-credentials`.
2. Call LiteLLM `POST /key/block` with `{ "key": "<token_id>" }` and verify success.
3. Call Den `POST /v1/llm-providers/:id/member-credentials/:orgMembershipId/block`.
4. Verify the member's connect request returns HTTP `200`, null credentials, and `memberCredential.state: "blocked"`.
Run `node provision.mjs offboard <orgMembershipId>` to perform that sequence. The integration is proved against a real LiteLLM database and a cold Den by `evals/specs/litellm-per-member-credentials.e2e.test.ts`.
@@ -0,0 +1,147 @@
---
title: "Sharing MCP connections with your team"
description: "Share Notion, Linear, Stripe, Exa, or any MCP server in OpenWork Cloud with Individual accounts by default, or One org account when everyone should act as the same account"
---
Use `Connectors` when you want the organization to manage an MCP integration once
— the server URL, who can use it, and how people sign in — instead of every
member configuring Notion or Linear by hand on every machine.
Two ways to handle whose account the AI uses, chosen per connection:
- **Individual accounts** — each person signs in as themselves. This is now
  the default for OAuth servers, and it fits tools like Notion or Linear where
  people have their own pages, projects, and permissions. The agent acts as
  *you*, and the provider's own access rules apply.
- **One org account** — an admin signs in once (a bot, service account, or API
  key). Every granted member's AI acts as that identity.
## Publish the connection in OpenWork Cloud
1. Open `Connectors` in the OpenWork Cloud dashboard.
2. Click `Add connection`.
3. Pick a preset (Notion, Linear, Stripe, Sentry, Exa, Context7) or enter any
   MCP server URL.
4. Choose the account mode: `Individual accounts` or `One org account`.
5. Choose who can use it: the whole workspace, specific teams, or specific
   people.
6. Click `Create`.
<Frame>
  ![MCP Connections admin screen in OpenWork Cloud](/images/cloud-mcp-connections-admin.png)
</Frame>
For a One org account connection, finish by clicking `Connect` and completing
the provider's sign-in as the org account. Individual accounts connections are
ready to publish immediately — each person connects themselves.
On `Your Connections`, an unconnected One org account connection shows
`Waiting for an admin to connect` to members. Workspace owners and admins get a
`Connect` button on that row so they can finish the org account sign-in there.
## OAuth redirect URL
An OAuth redirect URL, also called a callback URL, is the exact address where
the provider sends the browser after a person approves access. It belongs to
your specific Den deployment; it is not the MCP server URL or the client
metadata URL.
New MCP connections on one Den instance share this redirect URL:
```text
<DEN_API_PUBLIC_URL>/v1/mcp-connections/oauth/callback
```
For the hosted OpenWork Cloud instance, the dashboard is
`https://app.openworklabs.com` and its public Den API origin is
`https://api.app.openworklabs.com`. Register this exact redirect URL with the OAuth
provider:
```text
https://api.app.openworklabs.com/v1/mcp-connections/oauth/callback
```
For a self-hosted instance whose public Den API is
`https://api.openwork.example.com`, register:
```text
https://api.openwork.example.com/v1/mcp-connections/oauth/callback
```
Use the exact scheme, hostname, optional path prefix, and port configured in
`DEN_API_PUBLIC_URL`. Providers compare redirect URLs exactly. Existing
connections created with an older per-connection callback keep that registered
URL automatically; do not change it just to reconnect.
## Slack
Slack's MCP server requires a pre-registered Slack OAuth app.
1. Create or open a Slack app in [Slack API apps](https://api.slack.com/apps).
2. Add this Den instance's OAuth redirect URL to the Slack app's
   `OAuth & Permissions` redirect URLs.
3. In OpenWork Cloud, add the Slack connection and paste the app's client ID
   and client secret.
4. Members open `Your Connections` and connect their own Slack account.
For the advanced local desktop-only setup, see
[Connect Slack as a custom MCP](/start-here/connect-your-stack/connect-slack-mcp).
## What members see in the desktop app
Granted members find the connection in `Settings` > `OpenWork Connect`, grouped by what
they need to do:
- **Needs your sign-in** — individual-account connections that require the
  member to authenticate or reconnect.
- **Needs admin setup** — connections that an organization admin still needs
  to configure or authenticate.
- **Ready to use** — connections ready for the agent, including accounts
  managed by the organization.
## Connect your account
1. Sign in to OpenWork, then open `Settings` > `OpenWork Connect`.
2. Find the service under `Needs your sign-in`, then click `Connect`.
3. Your browser opens the provider's own sign-in page. Approve access.
4. The browser shows `Connected` — return to OpenWork.
5. The connection updates by itself, no reload needed, and moves to
   `Ready to use`.
Your sign-in is stored in OpenWork Cloud, not on this machine — connect once
and every device you use is connected.
## Your agent can use it immediately
No restart, no resync. Ask for something the tool can do:
> Find the "Q3 launch" page in Notion and summarize it.
The agent searches the live capabilities available through OpenWork Connect,
then executes an exact match with **your** account — your permissions, your
audit trail on the provider's side.
<Frame>
  ![The agent executing an org-shared MCP tool in chat](/images/desktop-org-mcp-chat.png)
</Frame>
If a connection needs attention, the agent should tell you which account needs
action and direct you to `Settings` > `OpenWork Connect`.
## Notes for admins
- Members only see connections they've been granted — access is explicit
  (workspace-wide, team, or per-person), and it's enforced by the server on
  every request, not by the app.
- Removing a connection (or a member's access) takes effect immediately for
  every device.
- Members who already connected a tool directly in their desktop app keep
  their existing setup — publishing an org connection never removes or
  changes anyone's local configuration.
## Relationship to local MCP servers
[Add a custom MCP server](/start-here/connect-your-stack/add-an-mcp-server)
still works without a cloud account. Use that advanced path for local tools or
servers your organization does not provide. Use Connect for accounts and
services managed through OpenWork Cloud.
@@ -0,0 +1,27 @@
---
title: "Team prompt cards"
description: "Use desktop policies to show different suggested prompts to teams and members."
---
Organization prompt cards are an OpenWork Cloud desktop-policy feature. Admins manage them in Cloud, and assigned members see them in the desktop composer as task suggestions. Managing desktop policies requires an Enterprise plan; the API returns `402` when the org is not entitled.
## Create team prompts
1. Open the Cloud dashboard and go to `Settings > Desktop policies`.
2. Create a non-default policy for the audience. The default policy is org-wide only and cannot be assigned to members or teams.
3. Turn on `Organization prompt suggestions`.
4. Add 2 required prompts, and optionally a third. Each `Prompt` is limited to 500 characters; each `Description` is limited to 120 characters.
5. Assign the policy to `Members` or `Teams`, then save. The API stores those choices as `memberIds` and `teamIds`, so different departments can use separate non-default policies.
## Know what members see
<Frame>
  ![OpenWork desktop composer showing organization prompt cards assigned through a Cloud desktop policy](/images/desktop-team-prompt-cards.png)
</Frame>
1. The admin's `Description` becomes the card title in the desktop app.
2. The admin's `Prompt` becomes the card body and the text inserted into the composer.
3. Clicking a card fills the composer; it does not auto-send the task.
4. Boolean policy toggles combine across every matching policy: any `true` wins.
5. Prompt cards do not combine. The desktop uses one prompt set from the matching policy with the highest `Priority`; ties go to the earliest created policy, then the lowest policy id.
6. Members receive changes from `GET /v1/me/desktop-config`. The desktop loads its cached config first, refreshes on Cloud session/settings changes, and polls every hour, so reload or switch the active Cloud organization if a change is not visible.