Set up your host

The supported path

The tested path is Ubuntu x86-64, Bun 1.3.14 and accessible KVM. The current verification host runs Ubuntu 26.04. Other environments are not established by this test. If you use a Mac or Windows laptop, use a supported Ubuntu host you control; these instructions are not a native Mac/Windows installation guide.

Laufwerk installs its pinned Microsandbox library and platform runtime as dependencies. You do not need a separate global msb installation. Do not disable optional dependencies: the native platform package is required.

From a Mac or Windows laptop

Use your laptop as the terminal and browser. The workflows run on an Ubuntu x86-64 machine you control with working KVM access. A provider subscription by itself is not sufficient. An ordinary cloud VM may not support nested virtualization: check /dev/kvm before investing time in setup.

On your laptop, open Terminal (macOS/Linux) or PowerShell with OpenSSH (Windows), then connect:

ssh USER@YOUR_UBUNTU_HOST

Replace both placeholders with your host details. Run the following setup and tutorial commands in that SSH session. Sign in to your model provider on the Ubuntu host, not only on your laptop. Use SSH forwarding to open Studio locally.

Native macOS, Windows and WSL execution have not been verified for this release. If you don't have an Ubuntu/KVM host, stop here: this release does not yet offer a verified laptop-only onboarding path.

Install host tools

Run on the Ubuntu host:

sudo apt-get update
sudo apt-get install -y ca-certificates curl unzip git rsync util-linux
curl -fsSL https://bun.sh/install | bash -s 'bun-v1.3.14'

Open a new terminal, then check:

bun --version
command -v rsync flock
test -r /dev/kvm && test -w /dev/kvm && echo 'KVM is accessible'

Expect Bun 1.3.14, paths for both utilities, and KVM is accessible. If /dev/kvm is missing, the host needs hardware virtualization enabled; a cloud VM may require nested virtualization support. Installing packages alone cannot add it.

If the device exists but your user lacks permission, ask the host administrator to grant KVM access. On an Ubuntu machine you administer, the usual group setup is:

sudo usermod -aG kvm "$USER"

Log out and back in, then repeat the access check. Do not run the whole workflow as root to work around permissions.

Connect Codex

Install the official Codex CLI if it is not already available. On this same Ubuntu host, run:

codex login

Choose subscription login. Laufwerk alpha.6 reads the host's ~/.codex/auth.json; an API key is not a replacement. Follow the CLI's browser or device login instructions for a remote machine. Don't paste credentials into workflow files or the website.

Only one provider is needed. The first tutorial defaults to Codex. For a Claude subscription, install the official Claude Code CLI, complete its /login flow on the Ubuntu host, then change the generated laufwerk/workflows/coding/workflow.ts as described below.

Use a Claude subscription instead

After init --example coding, keep the generated coder agent and its other options. Replace its Codex import, harness and credential selection with:

import { createClaudeCode } from "@laufwerk/sdk/harness/claude-code";

// Inside the existing HarnessAgent options:
harness: createClaudeCode(),
sandbox: createMicrosandbox({ credentials: "claude-subscription" }),

Remove the old createCodex import. Run bun run --cwd laufwerk check and bunx laufwerk@0.0.1-alpha.6 doctor --provider claude, then continue with the same tutorial. The complete first-workflow trial on this page was verified with Codex; Claude has separate runtime smoke coverage, not a fresh-host tutorial trial.

Check local readiness

Before initialization, you can inspect the CLI and local provider readiness:

bunx laufwerk@0.0.1-alpha.6 --version
bunx laufwerk@0.0.1-alpha.6 doctor

After initialization, run doctor from the new project root again so it also checks the consumer package versions and identity. It checks local credentials and selected tools; it does not boot a VM or prove the provider is reachable. The first real workflow completes that check.

Your first run may download images and prepare agent tooling. It needs outbound internet access to package/image registries and the provider. Later runs may reuse prepared images. A long first setup is not the same measurement as model response time.

Where the data goes

Workflow state and transcripts are stored on the host. Agent prompts and the files or tool output included in a model request reach the configured provider. Local execution does not mean offline inference. Use the disposable public fixture first, not confidential customer data.

Using a remote host

Run the install and workflow commands over SSH on the Ubuntu host. To view Studio from your laptop, start Studio on the host, note the loopback port it prints, and forward that port with SSH:

ssh -N -L 3001:127.0.0.1:STUDIO_PORT USER@YOUR_HOST

Replace the uppercase placeholders, then open http://localhost:3001 on your laptop. Keep Studio private. The public documentation site is separate from this local UI.

Run your first workflow →