Create and run workbenches
You create a workbench by opening a profile. A profile is a saved recipe for a workbench; each time you open it, Kenaz starts a new workbench from it. You can have several workbenches open at once, including more than one from the same profile.
Profiles
Open Profiles in the sidebar, or click New workbench in the Workbenches list, which takes you there. The list of profiles is on the left and the editor on the right.
- + New profile starts from a template: the Kenaz Harness only, 4 CPUs, 16 GiB of memory and 64 GiB of disk.
- Dup copies a profile. Del deletes one, after a confirmation. You can't delete Daily Driver or your only profile.
- A profile with an open workbench shows a running badge.
Profiles are saved as JSON files in ~/.kenaz/profiles. Edit them in the
app rather than by hand.
What a profile sets
| Section | What you set |
|---|---|
| Identity | Name and description. |
| Work mode | An archetype, chosen when you create the profile. |
| Resources | CPUs (1 to 16), memory (1 to 64 GiB), disk (8 to 512 GiB), and the Workspace directory: the folder on your computer that is shared into the workbench at /workspace. If the folder doesn't exist, Kenaz creates it when the workbench opens. |
| Apps & Tools | Which apps run in the workbench, and the Primary app shown first. If the apps need more CPU or memory than the profile gives them, Size to fit raises the resources. |
| AI provider | Appears when an app needs a provider key, such as the Harness. See Network access and credentials. |
| Workspace toolchain | Kenaz scans the shared folder for project files and suggests toolchains to install. Optional. |
| Connectors | MCP connectors the workbench may use. You add connectors in the App Library first. |
| Egress | The network tier and allowed destinations. See Network access. |
| Context Bridge | Extra shared folders (read-only or read-write), extra network endpoints, environment variables, keychain credentials, and clipboard sharing in each direction. |
Click Save, or Save & open workbench to save and open it straight away. Save is blocked until the profile has a name and a workspace directory, and, when an app needs one, an AI provider choice.
On macOS, the editor warns you when the combination of apps and egress tier isn't in the published image catalog. See Workbench images.
Opening a workbench
Open a workbench from its profile with Save & open workbench. It appears in the Workbenches list while it starts. On macOS the stages are building or fetching the image, booting the VM, and waiting for the apps to answer. The row's Show log shows the workbench's startup log. Cancel stops a workbench that is still starting.
On macOS, each workbench is its own Tart VM, cloned from the image. Kenaz runs the VM without a display; you see its apps in the workbench window.
Before opening, Kenaz checks that your computer has room for the workbench. See Resources.
The workbench window
Each open workbench has its own window, titled Kenaz — Workbench. It has:
- a top bar with the workbench's name, state and resource use, and Stop or Resume;
- a rail on the left with one entry per app. Apps without a screen of their own, such as the headless browser and the Dev Toolchain, are listed under Background;
- the selected app in the middle. Apps you switch away from keep running;
- an agent activity panel on the right and an activity strip along the bottom. The Layout menu shows or hides them.
Kenaz reaches each app's web interface inside the VM through a local proxy
on 127.0.0.1.
Workbench states
| State | Meaning |
|---|---|
| Provisioning | Starting up. |
| Active | Running, with its window open. |
| Suspended | You closed the window. The VM keeps running and keeps using CPU and memory. Resume or Focus reopens the window. |
| Stopping | Shutting down. |
| Stopped | Shut down. |
| Crashed | The VM failed or disappeared. The list shows the reason, and Diagnostics loads the workbench's log. |
The Workbenches list has Focus, Suspend, Resume, Stop, Cancel, Re-Open, Remove and Diagnostics buttons, depending on the state.
Stopping, and what's kept
Stop closes the window and shuts the workbench down. On macOS Kenaz then deletes that workbench's VM.
- Kept: everything in the workspace directory and other read-write shared folders, because those live on your computer. The downloaded image stays cached for next time.
- Not kept: anything the workbench wrote inside the VM outside shared folders.
Re-Open starts a new workbench from the same profile, with a fresh VM.
Remove takes a stopped or crashed workbench off the list.
When you quit Kenaz
On macOS, quitting Kenaz leaves running workbench VMs running. On the next launch Kenaz picks them up again and reopens windows for active ones. A workbench whose VM is gone is shown as crashed.
Resources
Before a workbench opens, Kenaz checks:
- that the profile gives its apps enough CPU and memory;
- that one workbench doesn't ask for more than this computer allows: at most all CPUs but two, 75% of memory, and half of the disk's total size (not how full it is);
- that the total across your running workbenches fits the host budget;
- that there's enough free disk.
The default host budget is all CPUs but two and 75% of memory. Change it with Budget… in the Workbenches list. CPUs can be shared between workbenches (up to 1.5 times the budget); memory can't.
If the budget is the problem, a Not enough host resources dialog shows what is using it and lets you stop workbenches, edit the profile or adjust the budget, then Retry.
Freeing disk space
- Clean up… removes crashed workbenches and stopped ones older than a
number of days (7 by default), with their data folders under
~/.kenaz/workbenches. Running workbenches are never removed. - Reclaim disk… lists VMs, cached images and workbench folders, with their sizes. Nothing is selected for you, and deleting takes two steps. It also offers Nix store clean-up and removing the Nix builder VM, each after a confirmation.