# Workspace

> An open-source workspace built with Univer Office SDK: try it online, self-host it, connect existing agents with Workspace CLI, or work in Desktop.

- Human documentation: [https://docs.univer.ai/overview/examples/workspace](https://docs.univer.ai/overview/examples/workspace)

- Agent Markdown: [https://docs.univer.ai/overview/examples/workspace.md](https://docs.univer.ai/overview/examples/workspace.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.6.0`

- Source: [examples/workspace.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/examples/workspace.mdx)

---

**Univer Workspace** is an open-source Office workspace built on **[Univer Office SDK](https://docs.univer.ai/overview.md)**, in which people and agents work together. Editable Office content and data-bound Web Apps are organized into Personal and Team Spaces, together with sharing, collaboration, versions, and change review. The [source repository](https://github.com/dream-num/univer-workspace) contains the application, the deployment configuration, the CLI, and the desktop client.

You can deploy Workspace on your own infrastructure or start with the [cloud trial](https://space.univer.ai). An existing agent connects through Workspace CLI. Workspace Desktop brings an agent conversation and the same workspace into a local application. All of these routes operate on the same service and the same files.

[Try online](#entry-points) · [Connect your agent](#cli-start) · [Self-host](#self-host) · [Desktop experience](#desktop-start) · [Source and customization](#build-your-own)

## Start with the cloud Workspace



Open the [cloud trial](https://space.univer.ai), sign in, and enter your Personal Space or a Team Space you can access. Create or open a document, then try direct editing, file organization, and sharing. The Workspace service is already running, so an agent can also connect to it through the CLI described below. The trial is intended for sample data, and that data may be reset.

**Workspace Server** manages identity, Spaces, permissions, storage, collaboration, and versions. **Web** is the browser interface for editing and review. A private deployment runs the same Server and Web application.

```mermaid
flowchart LR
H["Team members"] --> W["Online Web app<br/>Edit · Collaborate · Review"] --> S["Workspace Server<br/>Spaces · Content · Access · Versions"]
A["Your existing agent"] --> C["Workspace CLI<br/>Skills · Content tools"] --> S
```



## Connect your existing agent to the cloud Workspace

Install the CLI and the discovery Skill in the environment where your agent runs. Node.js 22.12 or newer is required, and Node.js 24 is recommended. An agent that can execute commands uses these tools while continuing to provide its own model and conversation. Set the cloud service explicitly so that the browser and the agent operate on the same Workspace:

```bash
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw --version
uvw config set workspace.origin https://space.univer.ai
```

#### First connection: sign in once in the browser

This step can be skipped when a valid session already exists. If sign-in is required, run:

```bash
uvw auth login
```

Open the returned link, sign in, and confirm the code in the browser. After the user confirms completion, run:

```bash
uvw auth login --complete
```

This step is required only when establishing a session. The [Workspace CLI guide](https://github.com/dream-num/univer-workspace/blob/main/apps/cli/README.md) documents the full command set and authentication.

After the browser authorizes the CLI once, the CLI reuses that session for later tasks. No agent-specific login page or authentication integration is required. Give the connected agent a task, then open the link it returns in Web: the content is the same, and the Agent's native Office changes can be reviewed before merging.

### Start with a document you can calculate and review

```text
Create an English monthly expense Sheet in my Personal Workspace Space with dates, categories, amounts, and five sample rows. Add a total formula and a chart by category.
Keep changes in an isolated draft, verify the data, formulas, and rendered result, and give me a preview or review link. Do not merge before I confirm.
```

Send this text to a connected agent or use it in Desktop. The agent creates and verifies the document, and you request changes, review the result, and decide whether to merge. The same content also opens in the online edition.

## Move the same workflow to your own deployment

The [open-source repository](https://github.com/dream-num/univer-workspace) contains Server and Web. Build the application with the [deployment guide](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker), then configure the domain, sign-in, persistent storage, and runtime settings. Development from source uses Node.js 24 and pnpm 11; the guide maintains the production deployment details.

Before deployment, prepare four parts:

| Part | What to configure |
| --- | --- |
| Service | A reachable Workspace URL and the Server + Web application. Desktop and CLI both connect to this deployment. |
| Persistent data | The product database, the collaboration database, and uploaded files, retained together. The default deployment stores them under `.data`; for Docker, mount a persistent volume. |
| Identity | Configure sign-in. When Desktop connects, register the Agent OAuth client with an exact callback URL match. |
| SDK license | Provide `VITE_UNIVER_LICENSE` when building Web for the deployment domain, and configure the license required by the Node.js content runtime separately. |

Model credentials belong to the Agent host and are configured separately from Workspace sign-in. The [deployment guide](https://github.com/dream-num/univer-workspace/blob/main/apps/workspace/README.md#docker) and [Agent setup](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md) describe the current settings.

Configure the same CLI to use the private deployment and authorize an account on that service. Replace the example address below with the actual service origin:

```bash
uvw config set workspace.origin https://workspace.example.com
uvw auth login
```

The agent keeps the same tools and Skills and now operates on the files and permissions of the private service. Desktop can also connect to that service. The [Agent connection guide](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#connect-to-a-local-workspace) documents client registration and callback configuration.

## Bring Workspace into a local Desktop client

**Workspace Desktop** combines Workspace, an agent runtime, Office tools, and content previews in one local client. Office work follows the conversation-and-preview pattern familiar from Codex or Cowork: describe the desired result, inspect the document or Web App beside the conversation, request a revision, and review the result.

Desktop can connect to the cloud Workspace described above, to a private deployment, or to a Workspace service running on the local machine. Models and conversations run through the configured agent host, while the connected Workspace manages files and access. The desktop examples below show how creation, management, and collaboration connect.

[Install and connect](#desktop-install) · [Try a budget review with two native documents](#desktop-first-task)

### Bring the agent workflow to everyday Office work

Office work continues after a conversation returns a downloadable file. People keep editing, calculate against real data, work with teammates, and decide which changes to accept. Desktop places these activities in one working environment.

- **Keep context:** conversations, files, local references, and Workspace material remain available.
- **Native Office content and Web Apps:** create, preview, and edit spreadsheets, documents, presentations, Relational Tables, and Canvases, and build interactive pages backed by Office data.
- **See and revise the result:** open content beside the conversation, inspect formulas and layout, then request a specific change.
- **Deliver through review:** the Agent's native Office changes remain in a Worktree until a person reviews them and merges them into the shared workspace.



### From a request to a reviewed deliverable

Office documents and Web Apps are generated and revised in ordinary conversation, then managed and shared in Space. Native Office changes pass through Worktree review before they merge. HTML publication and binding writes follow their own save and authorization flows. Later conversations can refer back to the same files and data.

```mermaid
flowchart LR
A["Conversation<br/>Request + sources"]
B["Office documents<br/>Worktree + change review"]
C["Web App<br/>HTML + data binding"]
D["Space<br/>Manage · share · collaborate"]
A --> B --> D
A --> C --> D
D -->|Continue with the same content| A
```

### What the desktop brings together

| Capability | Experience |
| --- | --- |
| Agent sessions | Conversations and task context, with the provider and model configuration managed locally. |
| Files and references | Browse the Spaces you can access. Use @ to reference Workspace files or folders, and local material. |
| Content previews | Open native Office files or Web Apps beside the conversation to check content, interactions, and data. |
| Review and delivery | See which documents a Worktree added, modified, or deleted, then request revisions, merge, or discard. |
| Local or hosted Workspace | Connect to the team's online service, or run the Workspace service on a local machine. |
| Space management and collaboration | Organize the files conversations produce, manage sharing, and edit the same content with teammates. |

### Workspace + Agent in practice

The screenshots below show a real macOS Desktop connected to a local Workspace and using fictional launch materials. This integration preview combines an extensible Agent host, the Space capability plugin, and a Univer brand skin; availability follows the project's releases.

#### Create and preview in a normal conversation

Describe the requirement in an ordinary conversation, and the Agent creates or revises Office documents and Web Apps. Previews appear on the right, and further refinements continue through conversation. The content is saved in Workspace, where Space manages files, sharing, and collaboration.

#### Sheets

**01 Launch Budget** combines budgets, actual spend, forecasts, variance formulas, and totals in one sheet. Charts compare budget against actual spend and show the variance for each workstream.

![Agent conversation beside the editable launch budget, formulas, totals, and comparison charts](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-spreadsheet.webp)

#### Docs

**02 Launch Brief** turns the goal, launch plan, success measures, and owner actions into an editable document.

![Agent conversation with the launch brief open in the Desktop document editor](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-docs.webp)

#### Slides

**03 Launch Story** turns the plan into a presentation with launch stages, an approval gate, and success measures, ready for team review.

![Launch presentation and slide thumbnails beside the Agent conversation](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-slides.webp)

#### Relational Tables

**04 Launch Plan** tracks tasks by phase, status, priority, and owner, and supports switching between the grid, status board, and phase views as work progresses.

![Launch task records with phase, status, priority, and owner fields in Relational Tables](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-relational-tables.webp)

#### Canvases

**05 Launch Map** connects launch stages on a canvas, placing deliverables, owners, and approval checkpoints in one visual plan.

![Launch stages, owners, and approval checkpoints on a canvas beside the conversation](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-canvases.webp)



The same conversation workflow also produces Web Apps. **06 Launch Dashboard** presents budget, actual spend, and variance as KPI cards, charts, and workstream detail. HTML View bindings let the page read spreadsheet data, so a team can use an interactive report beside its Office files. [Binding](https://docs.univer.ai/overview/features/shared/binding.md) remains experimental.

![Agent conversation beside the Launch Dashboard Web App with budget metrics and charts](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/conversation-dashboard.webp)

#### Manage the results in Space

Conversation results become files that the team continues to use. Space holds Office content and Web Apps in one place, with product categories, recent files, favorites, and personal or team spaces. The **All** view below collects material from **Aurora Launch Studio** and **Team Invitations**.

![Desktop Space home listing Office files and Web Apps from two project spaces](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/space-home.webp)

#### Continue editing and collaborating from Space

Open **01 Launch Budget** from Space to continue in the native spreadsheet editor. Budget lines, formulas, and totals remain editable, and comments, edit history, and sharing are available in the same view. Web and Desktop read the same Workspace files. Later Agent revisions can remain in a separate Worktree until review.

![Launch Budget line items open in Space with comments, edit history, and sharing controls](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/space-spreadsheet.webp)

#### Worktree and Compare: review before merging

In the **Intelligent Workbench**, Compare places the official budget beside the Agent's proposed changes. The draft adds two line items and updates the totals, and the change list and highlights identify the affected cells. Inspect content, formatting, or formulas, then merge or discard the draft. [Worktree](https://docs.univer.ai/overview/features/shared/worktree.md) isolates the draft, and [Compare](https://docs.univer.ai/overview/features/shared/compare.md) shows the differences.

![Official budget and Agent draft side by side in Compare, with added rows and changed totals](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/budget-compare.webp)

#### Share the document or Web App with the team

Open **Share** on the dashboard to check who can access the page and to copy its link. In this Team Space, the page inherits member permissions from the Space, and **Manage Space access** opens the location where those permissions are managed. Copying the link does not grant additional access.

![Launch Dashboard sharing dialog showing inherited Space permissions and link access](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/examples/workspace-desktop/space-sharing.webp)

### Install and connect

If an extensible agent desktop is already in use, the integration path is to install and enable the Space capability plugin, connect from Space, configure the model, and add a brand skin. The screenshots on this page use this composition. The full Workspace Desktop release and the plugin preview follow separate delivery paths; use the published release or the repository instructions for the installed version.

1. Choose a Desktop installer from [GitHub Releases](https://github.com/dream-num/univer-workspace/releases). Desktop releases use agent-v tags, so select the Windows x64, macOS Apple Silicon, or Linux x64 artifact for your machine. Desktop delivery is experimental, and availability follows the published releases.

2. In **Settings → Workspace**, choose the Workspace service, sign in through the browser, and authorize access. Connect to a deployed service or follow [local setup](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#connect-to-a-local-workspace) to run a service locally.

3. In Models settings, configure a supported provider, model, and credentials. Workspace sign-in and model access are configured separately; see [model configuration](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md#model-credentials).

4. Add an accessible Personal or Team Space, start a conversation, and use @ to reference source material. Run the task below, then open the content preview and the change review.

The installer includes the agent application and Office tools. The Workspace service runs separately, locally or remotely, and model access uses the configured provider.

### Try a budget review with two native documents

```text
In the current Space, create an English Budget Review spreadsheet with eight sample department rows: Department, Budget, Actual, and Variance. Use formulas for Variance and totals, and add a budget-versus-actual chart.
Create a short document summarizing the overspend and link it to the spreadsheet. Keep the native Office changes in one Worktree. Verify the values, formulas, and result, open the preview and change review, and wait for my approval before merging.
```

Follow up with: “Reduce Marketing’s budget by 10% and update the summary.” Check the revised values and document changes before accepting the draft.

## Build your own Workspace from the repository

The application described above is an Office SDK composition that can be adapted. Start from the [Workspace repository](https://github.com/dream-num/univer-workspace), reuse the content runtime and collaboration capabilities, and rebuild the workflows, Skills, tools, and interface around the team's requirements.

### Find the part you want to change

| Repository area | Responsibility |
| --- | --- |
| [`apps/workspace`](https://github.com/dream-num/univer-workspace/tree/main/apps/workspace) | Server, Web, product APIs, and deployment configuration. |
| [`apps/cli`](https://github.com/dream-num/univer-workspace/tree/main/apps/cli) | Connect existing agents to a deployed Workspace. |
| [`apps/agent`](https://github.com/dream-num/univer-workspace/tree/main/apps/agent) | Agent host, connection lifecycle, and the native Desktop shell. |
| [`skills/univer-workspace-cli`](https://github.com/dream-num/univer-workspace/tree/main/skills/univer-workspace-cli) | Discovery Skill installed into an existing agent. |
| [`packages/client-core`](https://github.com/dream-num/univer-workspace/tree/main/packages/client-core) | Shared Node-hosted Workspace content operations. |
| [`packages/dsh-univer-workspace-plugin`](https://github.com/dream-num/univer-workspace/tree/main/packages/dsh-univer-workspace-plugin) | Office tools, native previews, and task guidance for the agent host. |
| [`packages/dsh-univer-workspace-skin-plugin`](https://github.com/dream-num/univer-workspace/tree/main/packages/dsh-univer-workspace-skin-plugin) | Workspace branding and visual tokens. |
| [`packages/workspace-html-viewer`](https://github.com/dream-num/univer-workspace/tree/main/packages/workspace-html-viewer) | HTML View sandbox and data-binding host for Web Apps. |

### Skills: help agents understand the workspace and complete tasks

These Skills let an existing agent create and edit Office content and Web Apps in a connected Workspace, then hand the changes off for review. [Connect the agent to Workspace](#cli-start) first; the guidance below operates on the files and permissions of that service.

#### Skills for your existing agent

The [`univer-workspace-cli` Skill](https://github.com/dream-num/univer-workspace/blob/main/skills/univer-workspace-cli/SKILL.md) installed in the existing agent is the discovery entry point. It explains how to connect, locate the target, and load the operational guidance. The full runtime Skills ship with the CLI and match its commands and Facade APIs. The built-in capability plugin in Desktop also provides task guidance and tools.

| Guidance | Coverage |
| --- | --- |
| `core` | Locating Spaces and files, working in task drafts, checking content, and handing off for review. |
| `sheet` · `doc` · `slide` · `base` · `board` | Spreadsheets, documents, presentations, Relational Table, and Canvases. |
| `blob` | Uploading, downloading, and replacing original files. |
| `html-view` | Creating and managing live HTML pages for interactive Web Apps. |
| `embed` · `cross-unit-formula` | Embedding other content, and connecting data and formulas across content types. |

```bash
uvw skills list
uvw skills get core
uvw skills get sheet
uvw skills get html-view
```

Load `core` first, then the product or topic required by the task. `skills get` lists the reference paths; read one document with `uvw skills read <name> <path>`, or add `--full` to read all of them. Existing agents use these capabilities through the CLI, whereas Desktop integrates the tools and guidance into the conversation workflow.



#### Skills inside Desktop

The Desktop capability plugin includes the **univer** Skill and its references. It describes how Spaces and documents relate, how to use Office APIs, and how to create, check, and deliver a Worktree. The instructions accompany the executable tools, so the agent can look up an API, run it on native content, and inspect the result.

The [capability plugin](https://github.com/dream-num/univer-workspace/blob/main/packages/dsh-univer-workspace-plugin/README.md) combines file discovery, headless Facade editing, structured inspection, import and export, and the Worktree lifecycle tools. This preview prepares drafts for review; publishing goes through the review and merge workflow of the deployed application. An application can add domain Skills, templates, and business tools on the same Office runtime.

The preview plugin contains nine Skills. The common Skill covers discovery, identity, and delivery, and each product Skill covers its APIs and how to verify results. The agent reads the guidance required by the current task.

| Skill | Guidance |
| --- | --- |
| `univer` | Spaces, files, draft lifecycle, and delivery |
| `univer-sheet` | Formulas, styles, charts, and spreadsheet verification |
| `univer-doc` | Document structure, paragraphs, and tables |
| `univer-slide` | Slide authoring and visual layout checks |
| `univer-base` | Fields, records, and views |
| `univer-board` | Shapes, connectors, and canvas layout |
| `univer-embed` | Embedding one Office product inside another |
| `univer-cross-unit-formula` | Referencing and calculating across Units |
| `univer-html-view` | Building and inspecting HTML pages bound to Office data |





### How Office SDK powers Workspace

Workspace connects native editors, agent content operations, and team collaboration to the same documents and permissions. You can build on this open-source application and on Office SDK, and focus your effort on business workflows, interface, and integrations.

```mermaid
flowchart LR
A["Agent"] <--> S["Workspace Server"] <--> E["Editors"]
```

Agents operate on content in Node.js through the CLI or Desktop, and people view, edit, and review it in the Web or Desktop editor. Workspace Server stores shared documents, drafts, and collaboration state, and it can run locally, on private servers, or in the cloud.

| Layer | Responsibility |
| --- | --- |
| [Web SDK](https://docs.univer.ai/guides/sheets.md) | Content models, formulas, public Facade APIs, and native editors. |
| [AI SDK](https://docs.univer.ai/ai/content-operations.md) | API discovery, structured content inspection, and Facade execution on a specified document. |
| [Server SDK](https://docs.univer.ai/server.md) | Collaboration, revisions, Worktree drafts, and file conversion. |
| Application | Workspace handles Spaces, files, permissions, sharing, and review. The agent host handles conversations, model calls, and tool orchestration. |

CLI and Desktop share a [content operations layer](https://github.com/dream-num/univer-workspace/tree/main/packages/client-core). Its runtime pool keeps loaded documents alive for the lifetime of the host and synchronizes versions before execution. Different clients therefore reuse the same editing and submission logic. See [runtime reuse](https://docs.univer.ai/ai/runtime-architecture.md).

[Visual inspection](https://docs.univer.ai/ai/visual-inspection.md) complements structured checks. Screenshots come from browser rendering, and the automatic layout diagnostics currently detect text overflow and overlap in Slides.

#### From an agent edit to a reviewed change

In the budget-review example, the agent edits a spreadsheet that contains formulas and styles. The native Office editing path proceeds as follows:

1. **Locate and load.** The agent selects the document and Worktree, loads the snapshot and changesets, and synchronizes to the selected revision. A Unit is one document instance, such as a workbook.
2. **Edit through Facade.** The Node.js runtime executes public Facade calls against that Unit. Content changes produce mutations, which are collected into a changeset and submitted to the draft.
3. **Check the result.** The agent reads values and formulas back and inspects rendered output when necessary. Editing continues in the same draft until the result is ready for review.
4. **Review and merge.** A person checks the changes in [Compare](https://docs.univer.ai/overview/features/shared/compare.md) and decides whether to merge the [Worktree](https://docs.univer.ai/ai/worktree.md) into the shared version.

**Saving a changeset to a draft is not merging it.** Workspace reports a write as successful only after submission is confirmed; conflicts and unconfirmed submissions return errors. In the Desktop plugin, the merge and discard tools also require user approval, which the application's tool workflow enforces.

#### Connect Web Apps to the same Office data

The launch dashboard uses the same spreadsheet as the budget editor. HTML View renders the page in a sandboxed iframe. The Workspace host resolves the source documents that the user can access and supplies their authorized content engines. Metric cards and charts subscribe to the source data, so a second copy of the budget is not required.

For editable bindings, a write requires a signed-in identity and edit permission on the source document. When the user leaves the page, the host waits for pending writes and collaboration confirmation, and it reports save failures. HTML page publishing and binding writes use their own save paths and do not automatically follow the native Office Worktree merge flow. See [experimental data binding](https://docs.univer.ai/overview/features/shared/binding.md) and the [HTML View host implementation](https://github.com/dream-num/univer-workspace/tree/main/packages/workspace-html-viewer).

### Adapt the workflow to your own business

| Your goal | Where to start |
| --- | --- |
| Industry-specific documents and tasks | Add domain Skills, templates, and tool guidance, and retain content and visual checks. |
| Your own identity, storage, and sharing | Extend the Workspace application and its server-side product policies. |
| Your own agent-based Office client | Combine the agent host, the capability plugin, and a brand skin, then connect the chosen models and business tools. |

#### Example: add a budget-review Skill

A domain Skill can encode the team's review rules while reusing the existing Office tools:

- Locate the source workbook, the period, and the Budget/Actual columns, and ask about any missing business definition before editing.
- Load the spreadsheet guidance, create a Worktree, and use Facade to update formulas and prepare the review document.
- Check totals, formula results, and presentation, report the changed files and the checks performed, then hand the draft to a person for review.

Business rules and templates belong in the Skill. Access checks, draft persistence, and merge approval remain in the application. To connect an ERP or CRM, add an application tool that returns the required data and reuse the same Office editing and review flow. A Skill guides execution; it does not grant access to a file.



### Explore the implementation

[Desktop build and distribution](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/desktop/README.md) · [Agent application and configuration](https://github.com/dream-num/univer-workspace/blob/main/apps/agent/README.md) · [All examples](https://docs.univer.ai/overview/examples.md)

[Office Lab](https://docs.univer.ai/overview/examples/office-lab.md)
