Guest environment

The Kenaz Workbench sandbox runs Ubuntu 24.04. This page documents what is baked into the guest image, how the image is built, and what runs inside the sandbox during a session.

Note on naming: Earlier documentation referred to this layer as "SigilOS." SigilOS is no longer the guest OS. The current guest is a standard Ubuntu 24.04 image built from guest/distro/Dockerfile (WSL2) or guest/tart/build-image.sh (macOS Tart). "Sigil" in the Workbench context refers to the sigild event daemon from the sigil repo, not a custom OS.

What runs inside the sandbox

Three binaries are baked into the guest image during the build phase:

Binary	Source repo	Role
sigild / sigilctl	github.com/kameas-ai/sigil	Event daemon — forwards session events to the host-side ledger
kenaz-harness	github.com/kameas-ai/kenaz-harness	Task executor — handles inference dispatch, tool calls, and the audit log
workbench-app	github.com/kameas-ai/kenaz-workbench (guest/workbench-app/)	In-guest Wails app — the UI surface for the user

The Dockerfile also installs a baseline Ubuntu toolchain (git, curl, openssh-client/server, tmux, vim, ripgrep, jq, build-essential) and the GTK/WebKit2 runtime that the Wails workbench-app requires.

The workbench-app binary is a Wails v2 (Go + WebView) application. It runs inside the guest, not on the host. Its Wayland surface is delivered to the host desktop by the substrate:

• macOS: Tart's built-in VNC viewer surfaces the guest display.
• Windows: WSLg (the WSL2 GUI subsystem) surfaces the guest Wayland window natively on the Windows desktop.

No custom display transport code is needed on either platform.

How the image is built

Guest binaries are cross-compiled from the sigil and kenaz-harness repos then copied into the image at build time. On macOS (Tart path) the binaries are built for Linux/arm64; on Windows (WSL2 path) they are built for Linux/amd64.

# macOS — build arm64 binaries, then bake the Tart image
make binaries-arm64
make image-macos          # runs guest/tart/build-image.sh

# Windows — build amd64 binaries, then build the WSL rootfs tarball
make binaries             # runs guest/build-binaries.sh --arch amd64
make tarball              # runs guest/distro/build-tarball.sh

The pinned source references for each binary are recorded in guest/manifest.toml.

WSL2 guest image

The WSL2 image is an uncompressed Ubuntu 24.04 rootfs tarball produced by docker export of the Dockerfile. The launcher imports it with:

wsl --import <name> <installDir> <tarball> --version 2

The image configures a non-root kenaz user with passwordless sudo, and enables systemd via /etc/wsl.conf.

Tart guest image (macOS)

The macOS guest starts from the ghcr.io/cirruslabs/ubuntu:24.04 prebuilt image published by Cirrus Labs. The build script clones that base image locally with tart clone, boots it headlessly, rsyncs the compiled binaries in, and seals the result. The launcher later runs the sealed image with tart run --no-graphics.

What the workbench-app does not do

• Inference is not performed inside the guest. The kenaz-harness binary handles provider routing and policy; inference calls go over the harness's host API channel, not from within the sandbox.
• Persistent storage is not the guest's responsibility. Data that must outlive a session is written through the harness's audit-logged storage layer on the host. The sandbox itself has no persistent disk by default.
• waypipe, sway, and greetd are not present. The older vsock-and-kiosk display architecture was removed when the Workbench adopted the WSLg/Tart native display path. See ADR 0006 for the rationale.