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

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:

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) 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 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 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 resolves the endpoint and forwards requests to the local model server.

Configuration File Examples

Cloud Provider (OpenAI)

Organization-level configuration stored in opencode.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:

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

Key Implementation Files

• 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 – Handles UI for both cloud and local provider authentication and persistence.
• 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 – Parses and validates local provider configurations.
• 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.
• Local providers are configured client-side in opencode.jsonc, validated by custom-provider.ts, and resolved by 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) 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}