Skip to main content

​
Installation

Follow these steps to install the X21 Excel add-in on a Windows workstation. The add-in ships as a ClickOnce application signed with your team’s certificate and bundles the Deno backend, React task pane, and VSTO components.

​
Prerequisites

  • Windows 10 (build 19045+) or Windows 11 with Excel 2016 or later (desktop edition).
  • .NET Framework 4.8 – required by the VSTO runtime.
  • WebView2 Runtime (usually installed with Microsoft Edge). If missing, download from Microsoft.
  • Required ports available on localhost: 8000+ for the Deno API, 8085+ for WebSockets, and 8080+ for the Excel API bridge. The add-in automatically finds a free port close to these defaults and writes it to %LOCALAPPDATA%\X21\deno-*.
  • Valid keys for Anthropic (Claude), Langfuse, and PostHog if telemetry is enabled.

​
Choosing an Installation Channel

X21 publishes multiple ClickOnce channels through the Publish.ps1 script:
  • Dev – Local builds for rapid testing. Auto-increments the revision and skips uploads.
  • Internal – Internal QA environment hosted at https://dl.kontext21.com/internal/.
  • Staging – Pre-production validation (https://dl.kontext21.com/staging/). Requires branch dev.
  • Production – Main customer channel served from https://dl.kontext21.com/. Requires branch dev and a valid signing certificate.
  • ProductionLocal – Creates a versioned x21-setup-vX.Y.Z.W.zip in C:\x21\ for air-gapped deployment.
Double-check the Publish.ps1 environment config before distributing builds.

​
Installing via ClickOnce

  1. Navigate to the ClickOnce URL for your target channel or run the generated setup.exe from the publish directory.
  2. Click Install. The bootstrapper installs the VSTO add-in, registers necessary registry keys, and places the backend binaries under %LOCALAPPDATA%\X21.
  3. Launch Excel. The first run may take ~10 seconds while WebView2 caches assets and the Deno backend writes its port files.
  4. Look for the X21 ribbon tab. Open the task pane using the Open Copilot button.
Tip: If Excel reports that macros are disabled, enable Trust access to the VBA project object model and ensure the signing certificate is in the Trusted Publishers store.

​
Verifying the Installation

After Excel starts, X21 performs several background checks:
  • The WebView task pane loads the React UI from the bundled assets.
  • The backend launches x21-backend.exe, which starts the Deno server (mod.ts) and writes deno-server-port-*.txt and deno-websocket-port-*.txt.
  • The VSTO add-in exposes its local HTTP API (/api/actions/execute). You can confirm it by running curl http://localhost:<port>/api/getMetadata.
  • Logs appear in %LOCALAPPDATA%\X21\publish\publish.log and %LOCALAPPDATA%\X21\X21-deno\Logs.
If any component fails, review the Troubleshooting section for recovery steps.

​
Updating or Repairing

X21 uses ClickOnce auto-updates. On startup, Excel checks the update manifest referenced in your channel’s PublishUrl. To force an update or repair:
  1. Close Excel.
  2. Launch setup.exe again from the channel URL. Click Update or Repair when prompted.
  3. If auto-update testing is required (Production), install the current version before shipping the next release as enforced by Publish.ps1.
For scripted redeployments, rerun Publish.ps1 -Environment <EnvName> and distribute the newly generated installer.