Your First Workstation

In this tutorial you'll go from zero to SSH'd into a local Ubuntu VM on your Mac. By the end, you'll understand the core werkr workflow: write a YAML manifest, apply it, and connect.

What You'll Build

A local Ubuntu 24.04 virtual machine running on your Mac via Lima. No cloud account required.

Prerequisites

Step 1: Create the Manifest

Create a file called my-first-workstation.yaml with the following contents: 

apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-first-workstation
  labels:
    team: tutorial
spec:
  os:
    id: ubuntu-24.04
  provider: lima
  resources:
    cpu: 4
    memory: 3
    diskSize: 50

Here's what each field means:

  • apiVersion - The werkr API version. Always werkr.dev/v1alpha1 for now.
  • kind: Workstation - Tells werkr this manifest defines a workstation.
  • metadata.name - A unique name for your workstation. You'll use this to connect, stop, and delete it.
  • metadata.labels - Key-value pairs used to match configurations to workstations (more on this in the next tutorial).
  • spec.os.id - The operating system image. Options include ubuntu-24.04 and debian-13.
  • spec.provider - Where to run the VM. Use lima for local workstations.
  • spec.resources - CPU cores, memory (GB), and disk size (GB) allocated to the VM.

Tip: YAML is sensitive to indentation. Make sure you use spaces (not tabs) and that nested fields are indented consistently with two spaces.

Step 2: Apply the Manifest

Run the following command to create your workstation:

wer apply -f my-first-workstation.yaml

You should see output confirming the workstation was created. Behind the scenes, werkr's worker process starts provisioning a Lima VM using the settings you defined.

Step 3: Check the Status

See how your workstation is progressing:

wer get workstation

You'll see your workstation listed with a status that progresses through these stages:

  • Pending - The workstation has been accepted and is queued for provisioning.
  • Provisioning - The VM is being created and configured.
  • Running - The workstation is ready to use.

Note: The first time you create a local workstation, werkr downloads the OS image. This can take a few minutes depending on your internet connection. Subsequent workstations using the same OS will start much faster since the image is cached.

You can run wer get workstation again after a minute or two to check if the status has changed to Running.

Step 4: Connect to Your Workstation

Once the status shows Running, open a shell:

wer shell --name my-first-workstation

You're now inside your Ubuntu VM. The prompt should change to reflect the workstation environment.

Note: Use --name (not a bare argument) to specify which workstation to connect to.

Step 5: Look Around

Try a few commands inside the VM to confirm everything is working:

# Check the OS
cat /etc/os-release

# See who you're logged in as
whoami

# Check available memory
free -h

You should see Ubuntu 24.04 details, your username, and the memory you allocated in the manifest.

Step 6: Exit and Check Status

Type exit or press Ctrl+D to leave the VM shell.

Back on your Mac, check the workstation status again:

wer get workstation

The workstation is still Running - exiting the shell doesn't stop it. It stays available for you to reconnect anytime.

What Just Happened?

Here's a recap of the workflow you just completed:

  1. You wrote a YAML manifest describing the workstation you wanted.
  2. wer apply sent that manifest to werkr's local API.
  3. The worker picked up the request and provisioned a Lima VM on your Mac.
  4. You connected via wer shell, which set up an SSH session into the VM.

This same pattern - manifest, apply, connect - works for remote cloud workstations too. The only difference is the provider and where the VM runs.

Next Steps

Your workstation is running, but it's a bare Ubuntu install. In the next tutorial, you'll learn how to add development tools and customize your environment using a WorkstationConfig.