# How to Configure Cloud and Local Providers in OpenWork: Complete Setup Guide

> Discover how to configure cloud and local providers in OpenWork. Learn to set up organization-level server storage for cloud and define local providers in opencode.jsonc for seamless client-side resolution.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: how-to-guide
- Published: 2026-07-31

---

**OpenWork configures cloud providers through organization-level server storage that materializes credentials into workspaces, while local providers are defined directly in the user's `opencode.jsonc` file and resolved client-side without server interaction.**

OpenWork treats every AI model source as a **provider**, distinguishing between cloud-hosted services and self-hosted local servers. Understanding how each provider type is configured—whether through centralized organization settings or local device configuration—is essential for setting up model access correctly. This guide examines the complete configuration pipeline implemented in the `different-ai/openwork` repository.

## Provider Architecture: Cloud vs. Local

OpenWork supports two distinct provider types with different storage mechanisms and resolution paths.

### Cloud Providers

**Cloud providers** (OpenAI, Anthropic, Google, OpenRouter) store configuration in the organization's cloud-provider config on the server. When imported into a workspace via the Provider Auth Modal, these settings persist in the organization's `opencode.jsonc` file. The workspace then materializes credentials locally using **cloud-provider-materialization** logic, injecting API keys or OAuth tokens into the execution environment.

### Local Providers

**Local providers** (Ollama, self-hosted model servers) live entirely in the user's local `opencode.jsonc` file. The client reads these blocks directly without server round-trips. The **local-provider** kernel resolves model names and endpoints, routing requests to the locally-running model server.

## Core Data Structures and Validation

All provider references use the `openworkProviderRefSchema` Zod validation defined in [`packages/types/src/openwork-provider.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/openwork-provider.ts):

```typescript
export const openworkProviderRefSchema = z.string().trim().min(1);

```

Provider blocks store configuration under the `"providers"` key (or `"cloudProviders"` for organization-level configs) following the `openworkProviderCatalogSchema`. This schema validates provider IDs, credentials, and optional model lists.

## Cloud Provider Configuration Flow

The cloud provider setup follows a four-step materialization process:

1. **Discovery** – The UI fetches available providers from `/api/v1/providers`.

2. **Selection and Authentication** – The Provider Auth Modal ([`apps/app/src/react-app/domains/connections/provider-auth/provider-auth-modal.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/domains/connections/provider-auth/provider-auth-modal.tsx)) displays authentication options including OAuth, API key entry, or cloud import.

3. **Credential Submission** – 
   - **API key**: `onSubmitApiKey` stores the key in the organization's secret store and writes the provider block to `opencode.jsonc`.
   - **OAuth**: The flow completes server-side, returning a provider block for persistence.
   - **Cloud import**: `onConnectCloudProvider` copies existing organization config into the workspace.

4. **Materialization** – The [`cloud-provider-materialization.ts`](https://github.com/different-ai/openwork/blob/main/cloud-provider-materialization.ts) module validates the persisted block and injects secrets into the runtime environment, surfacing "provider config incomplete" errors to the UI when validation fails.

## Local Provider Configuration Flow

Local providers follow a client-side configuration path:

1. **Adding the Provider** – Users select "Add provider", choose a local option like Ollama, and paste a JSON/JSONC configuration into the UI textarea.

2. **Validation** – The [`custom-provider.ts`](https://github.com/different-ai/openwork/blob/main/custom-provider.ts) module parses and validates the config against `openworkProviderRefSchema`, throwing a `CustomProviderConfigError` for malformed entries.

3. **Persistence** – Validated blocks write directly to the user's local `opencode.jsonc` without server involvement.

4. **Resolution** – When referenced, [`apps/app/src/react-app/kernel/local-provider.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/kernel/local-provider.ts) resolves the endpoint and forwards requests to the local model server.

## Configuration File Examples

### Cloud Provider (OpenAI)

Organization-level configuration stored in `opencode.jsonc`:

```jsonc
{
  "providers": {
    "openai": {
      "type": "cloud",
      "credential": {
        "apiKey": "sk‑YOUR_OPENAI_KEY"
      },
      "selectedModels": ["gpt‑4o", "gpt‑4‑turbo"]
    }
  }
}

```

### Local Provider (Ollama)

User-level configuration saved directly to local `opencode.jsonc`:

```jsonc
{
  "providers": {
    "ollama": {
      "type": "local",
      "endpoint": "http://127.0.0.1:11434",
      "model": "llama3:8b"
    }
  }
}

```

## Key Implementation Files

- **[`packages/types/src/openwork-provider.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/openwork-provider.ts)** – Defines the provider reference schema and catalog types.
- **[`apps/app/src/react-app/domains/connections/provider-auth/provider-auth-modal.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/domains/connections/provider-auth/provider-auth-modal.tsx)** – Handles UI for both cloud and local provider authentication and persistence.
- **[`ee/apps/den-api/src/llm/cloud-provider-materialization.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/llm/cloud-provider-materialization.ts)** – Validates and injects cloud provider secrets into the runtime environment.
- **[`ee/apps/den-api/src/llm/custom-provider.ts`](https://github.com/different-ai/openwork/blob/main/ee/apps/den-api/src/llm/custom-provider.ts)** – Parses and validates local provider configurations.
- **[`apps/app/src/react-app/kernel/local-provider.ts`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/kernel/local-provider.ts)** – Resolves local provider requests and routes to model servers.

## Summary

- **Cloud providers** are managed centrally in organization configs, materialized into workspaces through server-mediated flows defined in [`cloud-provider-materialization.ts`](https://github.com/different-ai/openwork/blob/main/cloud-provider-materialization.ts).
- **Local providers** are configured client-side in `opencode.jsonc`, validated by [`custom-provider.ts`](https://github.com/different-ai/openwork/blob/main/custom-provider.ts), and resolved by [`local-provider.ts`](https://github.com/different-ai/openwork/blob/main/local-provider.ts) without server interaction.
- Both types use `openworkProviderRefSchema` for validation and store configuration in JSONC blocks under the `providers` key.
- The Provider Auth Modal ([`provider-auth-modal.tsx`](https://github.com/different-ai/openwork/blob/main/provider-auth-modal.tsx)) serves as the unified entry point for both configuration types.

## Frequently Asked Questions

### What is the difference between cloud and local providers in OpenWork?

Cloud providers require server-side credential storage and materialization through the organization's config, enabling team-wide access to managed AI services. Local providers are confined to the user's device, storing endpoint configurations directly in the local `opencode.jsonc` file for self-hosted models like Ollama.

### Where are cloud provider credentials stored?

Cloud provider credentials are stored in the organization's secret store on the server, with references persisted in the organization's `opencode.jsonc` file. The [`cloud-provider-materialization.ts`](https://github.com/different-ai/openwork/blob/main/cloud-provider-materialization.ts) module handles the secure injection of these credentials into the execution environment when models are invoked.

### How does OpenWork validate local provider configurations?

The [`custom-provider.ts`](https://github.com/different-ai/openwork/blob/main/custom-provider.ts) module parses local provider JSON/JSONC blocks and validates them against `openworkProviderRefSchema`. If validation fails, it throws a `CustomProviderConfigError` to prevent malformed configurations from being saved to the user's `opencode.jsonc` file.

### Can I use both cloud and local providers in the same workspace?

Yes. OpenWork supports mixed provider configurations within the same workspace. Cloud providers are imported from organizational settings via the Provider Auth Modal, while local providers are added directly through the UI and saved to the local configuration file, allowing seamless switching between managed APIs and self-hosted models.