Univer Workspace Deployment in Practice: AI Collaborative Editing of Office Documents
Univer Workspace Deployment in Practice: AI Collaborative Editing of Office Documents
Project Overview
Collaborative editing of office documents has always been a pain point in team collaboration, especially when AI Agents begin participating in content creation, making it a new challenge to let AI modify documents safely and controllably. Univer Workspace was born to solve this scenario: it is an independently deployable open-source Office workspace that allows you and AI Agents to work together on the same platform to handle Sheet, Doc, Slide, Base, and Board.
Its core design philosophy is worth noting. The Workspace consists of four parts: Browser, Server, Agent, and CLI:
- Browser provides the direct editing and collaboration interface, serving as the human operation entry point;
- Server is the only authority, responsible for identity authentication, permission management, and document storage;
- Agent is a local web application based on DSH, bringing together conversation, document preview, and change review;
- CLI provides a structured automation entry point for AI Agents, allowing document loading, modification, and verification to be done in the terminal.
The most impressive mechanism is the Worktree. Before the Agent modifies any content, the system first creates an isolated worktree where the Agent can freely edit and verify, generating a draft ready for human review, and only after approval is it merged into the main branch. This ensures that any intermediate changes do not pollute shared content, and humans always retain the final say.
Core Dependencies and Environment
Before you start, make sure your computer has the following basic environment ready:
- Node.js 24+: The Workspace server and frontend are both based on modern JavaScript and require Node 24 or higher.
- pnpm 11: The repository uses pnpm for dependency management, version requirement is 11.x, and it is recommended to enable it directly with
corepack enable. - Docker: If you take the container deployment route, you need Docker to run database and file storage services. For a quick local experience, you can use the default SQLite.
- Model service credentials: To configure a language model for the AI Agent, you need to prepare the API address and key of the model service, such as DeepSeek's
DEEPSEEK_API_KEY. - Workspace account: Accessing the Workspace requires login, and password registration is enabled by default.
Project Structure Tree
After cloning the repository, you will see the following directory layout:
apps/workspace Workspace Browser, Server, HTTP contract, and deployment application
apps/cli Remote Workspace automation application for Agents
apps/agent Workspace Agent application for document conversation and Worktree review
packages/client-core Private Node-hosted Workspace Agent Client capabilities
packages/reference-provider Private referenced-Unit policy used only by Browser
packages/dsh-univer-workspace-plugin Workspace capabilities and browser UI for Workspace Agent
packages/dsh-univer-workspace-skin-plugin Visual skin for Workspace Agent
scripts SDK versions and CLI local release tools
apps/workspace is the core, containing the Browser frontend, Server backend, and API contract. apps/cli is the command-line tool for AI Agents, while apps/agent is the desktop-level conversation interface.
Step-by-Step Guide
1. Prepare Source Code and Environment
First, clone the repository locally, install dependencies, and copy the environment variable example:
git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
pnpm install
cp apps/workspace/.env.example apps/workspace/.env
The default configuration uses SQLite and local file storage, which works out of the box. If you are deploying to production, modify the database and storage configuration in apps/workspace/.env as needed.
2. Start Workspace Services
Start the backend Server, which will run on http://127.0.0.1:3020:
pnpm workspace:dev:server
In another terminal, start the frontend Browser development server:
pnpm workspace:dev:web
Now open http://127.0.0.1:5173; Vite will automatically proxy API and WebSocket traffic to the Server on port 3020. Register an account with a password, and after logging in, you will have an editable Workspace.
3. Connect AI Assistant and Model Service
To let AI help you process documents, you need two independent connections: one is the Workspace login credentials for the AI to access your documents, and the other is the model service credentials to give the AI a "brain" to think.
First, the model service. The model settings of Workspace Agent are local machine state and are not bound to the Workspace user. You can inject them directly via environment variables. Before starting the Agent, run:
export DEEPSEEK_API_KEY=<your-api-key>
If you want more options or more flexible pricing for model services, you can check out Defapi. Defapi is an aggregation model gateway that provides model services at half the official price, compatible with mainstream protocols such as v1/chat/completions, v1/messages, and v1beta/models/. After obtaining the API root address and model ID from the platform, inject them in the same environment variable manner. Note that this is an external client configuration, not a built-in Workspace feature.
Then register the OAuth callback. Workspace Agent requires browser OAuth login. The official documentation suggests checking apps/agent/README.md for installation instructions. When installing the Agent, the local launcher will print the full token URL, and you need to complete application registration and callback configuration.
4. Install and Start Workspace Agent
The Agent is a local web application based on DSH; refer to apps/agent/README.md for installation steps. After installation, start the Agent, which will guide you to select or start your own Workspace service, register the OAuth callback, and then open the login page.
After logging in, you can use @ in the Agent's conversation interface to reference files in the Workspace, and the Agent will read the file content and make modifications.
5. Execute Office Document Tasks
Now let's have the Agent modify a spreadsheet. In the conversation, enter:
Please look at the Sheet @sales data, summarize the sales figures for each quarter of 2024 into a new Sheet, and annotate the growth rate.
The Agent will create a new Worktree and perform reading, calculation, and writing operations within it. This process does not affect the original data on the main branch.
6. Review Results and Merge After Approval
After the Agent completes the modifications, the Worktree will enter the Ready state. Back in the Browser or the Agent's review interface, you will see:
- A comparison view of the Agent's draft and the main branch
- Modified cells and newly added Sheets
After carefully verifying the data, click Merge. Only then will the changes actually be merged into the main branch, and all collaborators will see the updates. If you find issues, you can mark Reopen to let the Agent continue modifying.
Here is an alternative route using the CLI. Taking Claude Code as an example, if your Agent's runtime environment has univer-workspace-cli installed, you can do the following:
npm install --global univer-workspace-cli@latest
npx skills add dream-num/univer-workspace --skill univer-workspace-cli -g
uvw config set workspace.origin http://127.0.0.1:3020
uvw auth login # after browser confirmation
uvw auth login --complete
uvw pr list -R <owner>/<slug>
The CLI treats Worktrees as PRs. Copy the Worktree id returned by uvw pr view <n> -R <owner>/<slug> --json id, and you can use content commands to inspect it.
Common Troubleshooting
Node.js version too low at startup
Workspace requires Node.js 24+, check the version with node -v. If the version is insufficient, use nvm to install an LTS version.
pnpm install hangs or errors
The repository is fixed to pnpm 11.24.0; first run corepack enable and then execute the install. If network issues cause failure, set a mirror source and retry.
Opening port 5173 in the browser shows nothing
Make sure both terminals are still running: pnpm workspace:dev:server and pnpm workspace:dev:web. Vite's proxy requires the Server to start successfully first.
OAuth login shows callback address mismatch
Check whether the callback address in the Agent configuration matches the Workspace's authorized callback list. For local development, the callback is usually http://127.0.0.1:<agent-port>/oauth/callback.
Agent conversation prompts that model credentials cannot be found
Model credentials are local state and do not follow the Workspace user. Confirm that DEEPSEEK_API_KEY has been exported before starting the Agent or that the model has been configured via the DSH Models page. Different Agent processes need separate configurations.
Merge prompts lack permission
Merging a Worktree requires document edit permissions. In the Browser, check whether the current account has write permission for the corresponding folder or file. If the document is in a team Space, the Owner or Admin must assign permissions.
Extended Reading / Advanced Directions
If you wish to use Univer Workspace more deeply, these directions are worth exploring:
- CLI advanced usage: Read
apps/cli/README.mdto learn aboutuvw executefor running custom scripts,uvw inspectfor inspecting document structure, anduvw screenshotfor rendering screenshots to verify layout. - MCP service integration: Workspace provides a remote MCP service; configure
https://<your-workspace>/mcpinto Claude, Cursor, or VS Code to let these AI assistants directly operate your documents. - HTML View mini-app: The Agent can generate a web app bound to report data, with metrics, charts, and controls bidirectionally linked to cells, suitable for decision dashboards.
- Docker deployment: Switch to PostgreSQL + S3 storage, refer to
apps/workspace/README.mdfor containerized deployment, supporting automated upgrades and data migration.
Build a Workspace yourself and let AI help you handle the first monthly report. You will feel the sense of control brought by the Worktree review mechanism.