Univer Workspace: Deployment and AI Spreadsheet in Practice

AI-generated spreadsheet content gets stuck in the chat window, breaking subsequent editing, collaboration, and review. Univer Workspace puts documents, spreadsheets, and AI operations into the same workspace, letting an Agent make changes in an isolated Worktree that we review before merging. Today we'll complete a local deployment together, and use a sales spreadsheet to walk through Agent-generated summaries and formulas.

Project Introduction

Univer Workspace is an open-source Office workspace built on the Univer Office SDK that can be deployed independently. The core problem it solves: AI-generated office content has to be manually moved into an editor, making subsequent editing hard to collaborate on and review.

The project connects three entry points—Browser, Agent, and CLI—to the same Workspace Server, letting humans and AI work together on Sheet, Doc, Slide, Base, and Board. The Agent works in an isolated Worktree and verifies changes; only content we confirm gets merged into the shared trunk. You can edit directly in Workspace Browser, or have the Workspace Agent chat alongside documents and generate content, then review spreadsheet changes the way you'd review code.

Applicable Scenarios and Prerequisites

A typical scenario is sales data analysis. Teams put a sales detail spreadsheet into Workspace, have the Agent summarize by region and generate formulas, and review spreadsheet changes like code review.

Before you start, prepare:

  • Ability to operate a terminal and read JavaScript/TypeScript configuration
  • Git installed
  • Node.js 24 or higher
  • pnpm 11.24.0
  • A model API Key for Agent conversations
  • Chrome/Chromium when running screenshots or layout checks

Workspace login and model credentials are two different things: browsing documents doesn't require model requests; model credentials are only needed when talking to the Agent.

Core Dependencies and Environment

The repository's .npmrc points @univer-cli, @univerjs, @univerjs-pro, and @univerjs-labs to https://insider-npm-registry.univer.work/. Installation requires access to this private Registry as well as the public npm Registry.

DSH Runtime is pinned by packages/dsh-runtime to @deepseek-ai/[email protected]. The source code uses Apache-2.0, but the terms of use for the Univer SDK are not exactly the same as the source license: built-in runtime development credentials rotate every 90 days, and the server-side Collaboration/Exchange SDK requires a license key; if either value is missing, it falls back to free quota.

Project Structure Tree

apps/workspace                 Workspace Browser, Server, HTTP contracts, and deployment app
apps/agent                     Workspace Agent for document chat and Worktree review
apps/cli                       Remote Workspace automation app for Agents
packages/client-core           Private Node-hosted Workspace Agent Client capabilities
packages/dsh-runtime           Pinned DSH runtime version and dependency graph
scripts                        SDK version and release tooling

Step-by-Step Guide

1. Clone a fixed version and install dependencies

First pin to the commit used in this tutorial so later changes don't affect the commands.

git clone https://github.com/dream-num/univer-workspace.git
cd univer-workspace
git checkout c1a5fb3dc9d5951cbf618f76639466feac5da4d7
pnpm install --frozen-lockfile

This step accesses the private Registry and the public npm Registry. If your network is restricted, see the FAQ at the end.

2. Configure model access

Before starting the Agent, understand the division between login and model credentials. Workspace login only authorizes data access; when talking to the Agent, DSH sends model requests to the chat completions endpoint we configure. If you plan to have the Agent analyze the sales spreadsheet and generate formulas, prepare a baseURL, API Key, and model usable by the model.

DSH's deepseek-official adapter sends requests to baseURL + /chat/completions, so baseURL should be set at the /v1 level; don't append the path again.

If you want to control model costs, you can use an OpenAI-compatible gateway like Defapi. Defapi provides unified model access, marketed at roughly half the official pricing; the specific models and prices are subject to the console. The official site https://defapi.org has a clear entry point, and it is broadly compatible with v1/chat/completions, v1/messages, and v1beta/models/ protocols. When configuring, just point baseURL to the chat completions base address given by the Defapi console.

export DEEPSEEK_API_KEY="<Defapi 控制台创建的 API Key>"
export DEEPSEEK_BASE_URL="<Defapi 控制台显示的 chat completions 基址,例如 https://xxx/v1>"
export UWH_MODEL_SETTINGS_ENABLED=true

The model ID depends on what is actually available in the console. If DSH's default model ID doesn't match the Defapi console, you can change it to an ID available in the console from the model list on the DSH Models page. The Models page is hidden by default in production; setting UWH_MODEL_SETTINGS_ENABLED=true makes it visible; locally, without NODE_ENV=production, the native DSH Models page can be opened directly.

3. Create Workspace environment configuration and register the Agent OAuth client

Workspace does not register the Agent OAuth client by default; just copying .env.example is not enough.

cp apps/workspace/.env.example apps/workspace/.env

Then edit apps/workspace/.env and add the uncommented one-line configuration:

OAUTH_CLIENTS_JSON={"clients":[{"clientId":"univer-workspace-harness","clientType":"public","requiresConsent":true,"redirectUris":["http://127.0.0.1:3101/auth/oauth/callback"],"scopes":["identity","session"]}]}

If you already have OAUTH_CLIENTS_JSON, append the client above to the clients array, and always keep only one configuration item.

4. Start Workspace Server and Browser

In the first terminal, start the Server:

pnpm workspace:dev:server

In the second terminal, start the Browser dev server:

pnpm workspace:dev:web

Open http://127.0.0.1:5173, register a local Workspace account or log in with an existing account. Local registration does not require GitHub/Discord OAuth. Keep both processes running.

5. Build the DSH Runtime and Agent Profile, start the local Agent

The Agent is a local web app; you need to assemble the DSH runtime from source first. The commands below build client-core, three bundles, and install the Profile into an isolated directory.

export UWH_LOCAL_ROOT="${XDG_CACHE_HOME:-$HOME/.cache}/univer-workspace-harness"
export UWH_DSH_BOOTSTRAP="$UWH_LOCAL_ROOT/dsh-cli"
export DSH_HOME="$UWH_LOCAL_ROOT/install"
export UWH_DSH_DATA_HOME="$UWH_LOCAL_ROOT/data"
mkdir -p "$UWH_DSH_BOOTSTRAP" "$DSH_HOME/internal-packages"
export UWA_PACKAGES="$(mktemp -d "$DSH_HOME/internal-packages/build.XXXXXX")"

pnpm --dir packages/dsh-runtime install --frozen-lockfile
pnpm --dir packages/dsh-runtime deploy --legacy \
  --filter @univerjs/univer-workspace-dsh-runtime \
  --prod --config.node-linker=hoisted "$UWH_DSH_BOOTSTRAP"
export DSH_BIN="$UWH_DSH_BOOTSTRAP/node_modules/@deepseek-ai/dsh/lib/bin.js"

pnpm --filter @univerjs/univer-workspace-client-core build
pnpm --filter @univerjs/workspace-agent build
pnpm --filter dsh-univer-workspace-plugin build
pnpm --filter dsh-univer-workspace-skin-plugin build
pnpm --filter @univerjs/workspace-agent pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-plugin pack \
  --pack-destination "$UWA_PACKAGES"
pnpm --filter dsh-univer-workspace-skin-plugin pack \
  --pack-destination "$UWA_PACKAGES"

export DSH_PLUGINS="file:$UWA_PACKAGES/univerjs-workspace-agent-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-plugin-0.1.0.tgz file:$UWA_PACKAGES/dsh-univer-workspace-skin-plugin-0.1.0.tgz"
NPM_CONFIG_USERCONFIG="$PWD/.npmrc" ./apps/agent/scripts/build-profile.sh

export UWH_RENDER_PAGE_ROOT="$PWD/packages/client-core/dist/render-runtime"
export UWH_RENDER_BROWSER="${UWH_RENDER_BROWSER:-$(command -v google-chrome || command -v chromium || true)}"

node apps/agent/scripts/start-local.mjs --port 3101 \
  --no-open --trusted-host 127.0.0.1

The command stays in the foreground at start-local.mjs; this is normal. Wait until stderr shows a line starting with dsh web:, then copy the entire URL line.

If port 3101 is taken, use a different explicit port and update redirectUris in step 3 accordingly.

6. Connect to Workspace and complete OAuth

Open the full URL printed by dsh web: in your browser; it contains a one-time ?token=.... DSH sets an HttpOnly Cookie and redirects to the root address.

# 复制启动器输出的完整地址,例如:
# http://127.0.0.1:3101/?token=<one-time-token>

Then in the Agent interface, go to Settings → Workspace and enter the local service address:

http://127.0.0.1:5173

Click Sign in to Workspace, and approve access on the Workspace authorization page. Workspace redirects to the local Agent callback, and the Agent exchanges the authorization code using PKCE. After returning, the sidebar should show the account and personal Space.

If the connection page keeps waiting, click Check again and keep start-local.mjs running.

7. Create a sample sales spreadsheet and let the Agent generate summaries and formulas

Open Files in the sidebar, choose a personal or team Space, create a new spreadsheet, and enter the sales details:

日期,区域,销售额
2025-01-05,华东,12800
2025-01-06,华南,9600
2025-01-07,华东,15100
2025-01-08,华南,14200

Go back to Chats, start a new conversation, type @ in the input box to select the spreadsheet you just created, then send:

@销售明细 请按区域汇总销售额,并在表格中新增一列计算每个区域的平均销售额。

After sending, the Agent validates references against the current Workspace and writes changes to the Worktree; it does not modify the shared trunk directly.

8. Review Worktree diffs, merge or discard

Open the Worktree tab and find the task in progress. The review view shows "Modification Effect" by default, and you can switch to "Diff" to see added, modified, and deleted documents. After confirming the results are correct, click "Merge"; if not satisfied, you can convert it to a draft or discard it. The shared trunk updates only after merging.

创建 Worktree
→ Agent 编辑并验证隔离草稿
→ Ready
→ 人工审阅
→ Merge 或 Reopen
→ trunk

If the Agent runs univer_lint or univer_screenshot, you need a version-matched static rendering page and Chrome/Chromium. When UWH_RENDER_PAGE_ROOT or a browser is missing, the tool reports a clear precondition error and does not mark visual verification as passed.

Troubleshooting Common Issues

1. pnpm install fails to access the private Registry

Installation requires access to both the private Registry and the public npm Registry; neither can be missing. If it hangs or returns 401, first confirm the network can reach https://insider-npm-registry.univer.work/, then confirm the Node and pnpm versions. Don't delete the registry line in .npmrc.

2. OAUTH_CLIENT_UNAVAILABLE appears

The Workspace server hasn't loaded the Agent OAuth client. Check whether OAUTH_CLIENTS_JSON in apps/workspace/.env contains univer-workspace-harness, then restart the Server after making changes. Just copying .env.example doesn't register this client.

3. INVALID_REDIRECT_URI appears

The callback address must match exactly. localhost and 127.0.0.1 are different registrations. If the Agent changes ports, update redirectUris accordingly and restart the Workspace backend. This registration controls the OAuth callback, not a general CORS allowance for port 3101.

4. Opening the root address returns 401

If you don't first open the full URL with the token, the browser has no session cookie. Reopen the dsh web: address printed by the launcher to complete the exchange; afterward you can use the root address without parameters. Don't reuse the one-time token.

5. Workspace login succeeds but model messages fail

Workspace OAuth only authorizes data access; model credentials need separate configuration. Check DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, and the model ID. When using Defapi, set baseURL to the chat completions base address from the console; don't append /chat/completions again.

6. The Agent connection page keeps waiting

Keep start-local.mjs running. After the connection status changes, a readiness check runs; if the account service fails to load, check the launcher logs. When the authorization request expires, log in again from Settings → Workspace. This flow uses browser OAuth and doesn't require entering a device code.

7. Screenshot/layout check reports a precondition error

univer_lint and univer_screenshot require UWH_RENDER_PAGE_ROOT to point to a static rendering page, and UWH_RENDER_BROWSER to point to a compatible Chrome/Chromium. If there is no browser, assign the executable path to UWH_RENDER_BROWSER and then start the Agent.

Further Reading / Next Steps

  • Docker deployment: Workspace provides a standalone deployment app. You can build images following the official app guide and put Server, Browser, and storage on a server.
  • CLI automation: Install univer-workspace-cli and connect existing Agent environments like Claude, Codex, Kimi Work, using the CLI to handle documents and Worktrees.
  • MCP integration: Workspace exposes a remote MCP service supporting Streamable HTTP and OAuth; clients like Cursor, VS Code, and Claude Desktop can connect directly.
  • Official docs and pinned version: Univer Web SDK docs, Server SDK docs, Workspace configuration docs. This tutorial is based on c1a5fb3dc9d5951cbf618f76639466feac5da4d7; for later versions, refer to the official docs.