Cloud Den API & Services
Relevant source files
The following files were used as context for generating this wiki page:
The Cloud Den API (referred to as den-api or the Den control plane) is a Hono-based service that acts as the central orchestration and management layer for the OpenWork ecosystem. It facilitates user authentication, organization management, worker lifecycle tracking, and synchronization of resources like LLM providers and marketplaces between the cloud and desktop environments.
The system is designed to be "local-first, cloud-ready," allowing users to run workflows on their own machines while optionally connecting to hosted workers and team-shared configurations. The Den API serves as the source of truth for organization-level policies, member roles, and shared assets such as skills and MCP (Model Context Protocol) servers.
Sources: ee/apps/den-api/README.md, AGENTS.md:14-22, ee/apps/den-api/src/app.ts:139-160
System Architecture
The architecture consists of a central API (den-api) and a frontend web application (den-web). The API is built using Hono and utilizes Zod for schema validation and TypeID for unique, prefixed identifiers.
The diagram shows the relationship between the central API, the web frontend, and the desktop client.
Sources: ee/apps/den-api/src/app.ts:40-60, ee/apps/den-web/README.md:7-12
Key Service Components
| Component | Description |
|---|---|
| Den API | The Hono-based control plane implementing organization CRUD, worker lifecycle, and SCIM management. |
| Den Web | The Next.js frontend for user signup, billing management, and cloud worker visualization. |
| Better Auth | Integration used for session management and SSO/SCIM plumbing. |
| Worker Proxy | Facilitates communication between the desktop app and remote workers. |
Sources: ee/apps/den-api/README.md, ee/apps/den-web/README.md, prds/scim/den-api-scim-plan.md:14-20
Authentication & Desktop Handoff
Authentication is handled via Better Auth, supporting standard providers and GitHub OAuth. A critical feature is the Desktop Handoff, which allows a user authenticated in the browser (den-web) to securely transfer their session to the desktop application.
Handoff Sequence
The sequence illustrates how session tokens are securely transferred from the browser to the desktop client.
Sources: evals/cloud-auth-flows.md:33-52, apps/app/src/app/lib/den.ts:600-615, apps/app/src/react-app/domains/settings/cloud/use-den-session.tsx:280-310
Resource Synchronization
The Den API manages several resource types that are synchronized to the desktop workspace opencode.jsonc configuration.
Supported Resource Types
- LLM Providers: Organization-managed model configurations (e.g., OpenAI compatible) with secure API key storage.
- Marketplaces: Repositories of plugins that can be imported to materialize local workspace files.
- Skills: Shared agent capabilities authored within an organization and distributed via "Skill Hubs."
- Workers: Remote compute instances (hosted on Daytona) that can be connected as remote workspaces.
Sources: evals/cloud-provider-sync-flows.md:1-20, evals/cloud-marketplace-sync-flows.md:1-15, apps/app/src/app/lib/den.ts:130-180
Sync Logic Flow
The desktop app polls the /v1/resources endpoint to retrieve a snapshot of the organization's state. If local config is out of sync, the app prompts the user to "Refresh" or "Import."
API Surface & Endpoints
The API is structured into focused route groups. Authentication is typically handled via Authorization: Bearer <session-token> or x-api-key.
Primary API Routes
| Path | Tag | Description |
|---|---|---|
/v1/me | Users | Current user session and membership details. |
/v1/orgs | Organizations | CRUD for organizations and active org context selection. |
/v1/llm-providers | LLM Providers | Manage organization-wide LLM gateway configurations. |
/v1/workers | Workers | Worker provisioning, heartbeats, and instance metadata. |
/v1/marketplaces | Marketplaces | Registry for plugins and configuration objects. |
/v1/scim | SCIM | Enterprise user provisioning connectors. |
Sources: ee/apps/den-api/src/app.ts:145-165, ee/apps/den-api/README.md:30-45
Data Identifiers (TypeID)
The system uses TypeID for consistent validation across the API and desktop. Examples include:
request_*: Unique ID for logging and tracing.org_*: Organization identifier.lpr_*: Cloud-managed LLM Provider identifier.
Sources: ee/apps/den-api/README.md:50-60, apps/app/src/react-app/domains/settings/cloud/use-den-session.tsx:120-130
Enterprise Features
SCIM Provisioning
The Den API includes a plan for SCIM (System for Cross-domain Identity Management) to allow organizations to automate user provisioning. It utilizes the better-auth/scim plugin but overrides destructive lifecycle behavior to ensure that deleting a user within an organization does not globally delete the user's OpenWork identity.
Sources: prds/scim/den-api-scim-plan.md:10-40
Organization Governance
Organizations can define custom roles, team boundaries, and "Skill Hubs" to restrict or share agent capabilities. Shared templates allow for distributing pre-configured workspace environments across the entire team.
Sources: ee/apps/den-api/src/app.ts:155-160, changelog/release-tracker-2026-03-20.md:510-525
Summary
Cloud Den API & Services provide the backbone for team collaboration and remote compute in the OpenWork project. By centralizing management of workers, providers, and skills while maintaining a local-first execution model, the system enables secure, scalable, and reproducible agentic workflows across organizations.