Skip to main content

Install and run the Workbench

This page covers how to get the Kenaz Workbench running on your machine. For an architecture overview see Overview; for the host launcher's session flow see Host launcher.

Requirements​

macOS​

  • macOS 13 Ventura or later, Apple Silicon (M1 / M2 / M3 / M4)
  • Tart installed: 
    brew install cirruslabs/cli/tart
  • Xcode Command Line Tools: 
    xcode-select --install
  • Go 1.24+ (for building from source)

Intel Mac is not supported in v1. Tart relies on Apple's Virtualization.framework, which is broadly Apple-Silicon-first.

Windows​

  • Windows 11
  • WSL2 enabled: 
    wsl --install
    # or, if WSL is already installed:
    wsl --set-default-version 2
  • Go 1.24+ (for building from source)

Download​

Pre-built binaries and guest images will be available at kameas.ai/download when the Workbench reaches general availability. Until then, build from source.

Build from source​

git clone https://github.com/kameas-ai/kenaz-workbench.git
cd kenaz-workbench

macOS​

# Cross-compile the Linux/arm64 guest binaries
# (requires sigil and kenaz-harness checked out alongside this repo)
make binaries-arm64

# Bake the Tart guest image
make image-macos

# Build the host launcher binary
go build -o ./out/launcher ./cmd/launcher/

Windows​

# Cross-compile the Linux/amd64 guest binaries (run in WSL)
make binaries

# Build the WSL2 rootfs tarball (requires Docker Desktop)
make tarball

# Build the host launcher binary
go build -o .\out\launcher.exe .\cmd\launcher\

First run​

# macOS / Linux
./out/launcher

# Windows
.\out\launcher.exe

The launcher binds 127.0.0.1:8181 and opens the URL in your default browser. If the browser does not open automatically, navigate to http://127.0.0.1:8181 yourself.

From the browser UI:

  1. Click Open Workbench.
  2. The launcher provisions the sandbox substrate (clones the Tart image or imports the WSL tarball) and starts the guest environment. This takes 15–60 seconds on first run because the image is copied or imported. Subsequent runs use the local clone cache and are faster.
  3. The workbench window appears in your browser tab's sibling — on macOS via Tart's built-in viewer; on Windows via the WSLg desktop.
  4. When you are done, click Close Workbench in the browser UI. The launcher tears down the sandbox and frees the substrate.

Verify your installation​

# macOS smoke test (runs provision → exec whoami → destroy)
bash scripts/smoke-macos.sh

# Windows smoke test
pwsh -File scripts/smoke-windows.ps1

Both scripts exit 0 on success and print step-by-step status to stdout.

Troubleshooting​

Tart is not on PATH : Run brew install cirruslabs/cli/tart and ensure /opt/homebrew/bin is in your shell's PATH.

WSL2 not found (Windows) : Run wsl --install in an elevated PowerShell prompt, restart, and try again.

Port 8181 already in use : Pass --addr 127.0.0.1:<port> to the launcher:

./out/launcher gui --addr 127.0.0.1:8282

Workbench window does not appear (macOS) : Check that tart can run VMs: tart run --no-graphics --help. If Tart complains about permissions, grant it in System Settings → Privacy & Security → App Management.

First run takes a long time (macOS) : The base Tart image (ghcr.io/cirruslabs/ubuntu:24.04) is roughly 5 GB. It is only downloaded once; subsequent launches use the local clone.