# How OpenWork Handles Local and Cloud Workspaces: Architecture and Implementation

> Discover how OpenWork manages local and cloud workspaces differently. Learn about direct filesystem mounts and HTTP API endpoints for efficient workspace control and access.

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

---

**OpenWork distinguishes local workspaces as direct filesystem mounts controlled by the `OPENWORK_WORKSPACE` environment variable, while cloud workspaces are remote entities managed via HTTP API endpoints with role-based access controls and persistent server-side state.**

The `different-ai/openwork` repository implements a dual-mode workspace architecture that supports both offline-first local development and collaborative cloud environments. Understanding how local and cloud workspaces differ in creation, persistence, and access control is essential for developers configuring AI-powered development environments.

## Architecture of Local and Cloud Workspaces

### Local Workspace Model

Local workspaces in OpenWork operate as direct filesystem mappings. When you point OpenWork at a directory using the `--workspace` flag or the `OPENWORK_WORKSPACE` environment variable, the system mounts your host directory (for example, `./workspace`) directly into the development environment. 

According to the local development documentation, this approach leverages the [`dev-headless-web.ts`](https://github.com/different-ai/openwork/blob/main/dev-headless-web.ts) script to read the environment variable and establish the filesystem binding. Files persist immediately to your local disk, making this mode fully functional without network connectivity and subject only to your operating system's native file permissions.

### Cloud Workspace Model

Cloud workspaces function as remotely-hosted entities identified by unique IDs and accessed via HTTP API endpoints. As implemented in the OpenWork Den server, creating a cloud workspace requires a `POST` request to the `/workspaces` endpoint, which returns a workspace record that the system then mounts at `/workspace` inside the container.

Unlike local workspaces, cloud implementations require network access to the Den host and synchronize state through REST calls. This architecture enables multi-user collaboration, shared access controls, and centralized AI model provisioning through provider keys (such as OpenAI or Anthropic tokens attached to the workspace).

## Key Differences Between Local and Cloud Workspaces

The implementation diverges significantly across several operational dimensions:

- **Location and Persistence**: Local workspaces live in directories on your host OS (e.g., `./my-workspace`) with immediate, offline-first persistence. Cloud workspaces exist on remote servers with state maintained through API synchronization.

- **Creation Method**: Local workspaces are created by simply pointing OpenWork at a folder path. Cloud workspaces require API interaction with the Den server (`/workspaces` endpoint) and return a workspace ID for subsequent operations.

- **Access Control**: Local workspaces rely on OS file permissions. Cloud workspaces enforce security through Den organization roles (owner, admin, member) and MCP-level permissions as documented in [`cloud-organization-role-access.md`](https://github.com/different-ai/openwork/blob/main/cloud-organization-role-access.md).

- **Provider Keys**: Local workspaces require no cloud provider keys; AI models run locally or via user configuration. Cloud workspaces mandate attached provider keys for remote inference capabilities.

- **Offline Capability**: Local workspaces function without network connectivity. Cloud workspaces require persistent network access to the Den host, falling back to local mode when disconnected.

## Implementation Details and Source Code References

### Local Workspace Configuration

The entry point for local workspace configuration resides in the project's development scripts. The [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) specifies that developers set the `OPENWORK_WORKSPACE` environment variable to point to a host path, which the CLI then uses to initialize the workspace context.

For containerized cloud runs, the [`scripts/evals/daytona-real-run.sh`](https://github.com/different-ai/openwork/blob/main/scripts/evals/daytona-real-run.sh) demonstrates mounting a workspace at `/workspace` inside a Docker sandbox, though this represents the cloud deployment pattern rather than local development.

### Cloud Workspace API Integration

Server-side APIs handle cloud workspace lifecycle management. Endpoints under `/workspace/:id/` manage health checks and role-based access, while the creation flow returns workspace records that the client application consumes.

The system requires valid bearer tokens and organization-level permissions for cloud operations, contrasting with the permissionless local filesystem approach.

### UI Components for Cloud Status

The React frontend distinguishes cloud workspaces through specific UI components. In [`apps/app/src/react-app/shell/cloud-workspace-overlay.tsx`](https://github.com/different-ai/openwork/blob/main/apps/app/src/react-app/shell/cloud-workspace-overlay.tsx), the application renders a status badge showing connection health and connectivity state.

This component also conditionally disables the new-workspace creation UI when cloud workspaces are unavailable, as referenced in `ee/apps/den-web/app/(den)/dashboard/_components/background-agents-screen.tsx`, which displays notices regarding cloud workspace availability.

## Practical Code Examples

### Starting OpenWork with a Local Workspace

Set the environment variable to mount a specific folder as your workspace:

```bash

# Mount a folder called "my-workspace" as the OpenWork workspace

OPENWORK_WORKSPACE=./my-workspace pnpm dev

```

The `OPENWORK_WORKSPACE` variable is read by the development scripts to establish the local filesystem binding.

### Creating a Cloud Workspace via the Den API

Use the REST API to provision a remote workspace with proper authentication:

```javascript
import fetch from 'node-fetch';

const base = process.env.OPENWORK_DEN_URL;
const token = process.env.OPENWORK_TOKEN;

const resp = await fetch(`${base}/workspaces`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'team-project' })
});
const { id: workspaceId } = await resp.json();

console.log('Created cloud workspace', workspaceId);

```

The returned `workspaceId` identifies your workspace for subsequent API calls and UI rendering.

### Accessing Cloud Workspace Status in the UI

The React application monitors cloud workspace health through dedicated hooks:

```tsx
import { useWorkspace } from '@/hooks/useWorkspace';

function CloudStatus() {
  const { workspace, health } = useWorkspace(); // pulls from /workspace/:id/health

  if (!workspace) return null;
  return (
    <div aria-label={`Open cloud workspace status: ${health.label}`}>
      {health.label}
    </div>
  );
}

```

This implementation mirrors the pattern used in [`cloud-workspace-overlay.tsx`](https://github.com/different-ai/openwork/blob/main/cloud-workspace-overlay.tsx) to display connectivity badges and health indicators.

## Summary

- **Local workspaces** use the `OPENWORK_WORKSPACE` environment variable to mount host directories directly, offering offline-first operation with OS-level permissions.
- **Cloud workspaces** are API-driven entities created through the Den server's `/workspaces` endpoint, requiring authentication, provider keys, and persistent network connectivity.
- The **cloud-workspace-overlay.tsx** component renders status indicators and controls UI availability based on cloud workspace health.
- **Access control** differs fundamentally: local workspaces use filesystem permissions while cloud workspaces implement role-based access (owner, admin, member) through the Den organization system.
- **Container mounting** for cloud environments occurs at `/workspace` inside the container, contrasting with direct host directory binding for local development.

## Frequently Asked Questions

### Can I use cloud workspaces offline?

No. Cloud workspaces require persistent network access to the OpenWork Den host for API synchronization and state management. When offline, OpenWork falls back to local workspace mode where files are stored and accessed directly from your host filesystem without remote dependencies.

### How do provider keys differ between local and cloud workspaces?

Local workspaces do not require cloud provider keys; AI model inference runs either locally or through your own configuration. Cloud workspaces require attached provider keys (such as OpenAI or Anthropic tokens) that are stored with the workspace record on the Den server for remote inference and team-wide model access.

### What controls access to cloud workspaces?

Cloud workspace access is enforced through Den organization roles including owner, admin, and member levels, as documented in the role-based access documentation. Local workspaces rely solely on your operating system's file permissions and directory ownership, with no additional authorization layer required.

### Where does OpenWork mount cloud workspaces inside containers?

According to the implementation in [`scripts/evals/daytona-real-run.sh`](https://github.com/different-ai/openwork/blob/main/scripts/evals/daytona-real-run.sh), cloud workspaces are mounted at `/workspace` inside the container environment. This contrasts with local workspaces, which maintain their original host path location (such as `./my-workspace`) throughout the development session.