Workstations

A Workstation is the core resource in werkr. It represents a development environment - either a local VM or a remote cloud instance.

Workstations are configured through Workstation Configurations which install tools, packages, set up port forwarding, and more. Access to Git repositories and remote hosts is provided through SSH Keys. Other means of controlling access and injecting credentials are coming soon.

API Definition

apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: <string>              # Unique name
  labels:                       # Key-value labels for matching configs and SSH keys
    <key>: <value>
spec:
  os:
    id: <string>               # ubuntu-24.04 or debian-13
  provider: <string>           # lima, aws, azure, gcp
  providerConfig:               # Provider-specific settings (see below)
    ...
  resources:
    cpu: <number>              # CPU cores (default: 2)
    memory: <number>           # Memory in GiB (default: 4)
    diskSize: <number>         # Disk size in GiB (default: 50)

Supported Operating Systems

OS ID Description
ubuntu-24.04 Ubuntu 24.04 LTS
debian-13 Debian 13 (Trixie)

Labels

Labels are key-value pairs attached to workstations. They are used by Configurations and SSH Keys to target specific workstations via label selectors. 

metadata:
  labels:
    team: platform
    env: dev
    project: api

Lifecycle

Workstations go through the following phases:

  1. Pending - Infrastructure is being created
  2. Provisioning - VM is booting and base setup is running
  3. WerProvisioning - Configurations are being applied (tools, packages, files)
  4. Running - Ready to use
  5. Stopped - Halted but disk preserved
  6. Deleting - Being torn down

Common Operations

# Create or update from manifest
wer apply -f workstation.yaml

# List workstations
wer get workstations

# Get details
wer get workstation my-dev-env

# Connect via SSH
wer shell --name my-dev-env

# Connect to a persistent tmux session
wer tmux --name my-dev-env

# Stop (preserves disk)
wer stop workstation my-dev-env

# Start again
wer start workstation my-dev-env

# Edit in default editor
wer edit workstation my-dev-env

# Copy a workstation blueprint to create a new one
# The copy is bootstrapped from the same configurations,
# without any manually applied changes from the original.
wer copy workstation my-dev-env --name my-dev-env-v2

# Delete
wer delete workstation my-dev-env

Lima (Local)

The lima provider runs workstations locally as Lima VMs. It is also meant as a tool to allow macOS users an easy and free mechanism to run a large set of container features, even for commercial purposes.

Platform: macOS only. Support for Windows and Linux is coming soon.
Availability: All versions of werkr.

Provider Config

spec:
  provider: lima
  resources:
    cpu: 4            # CPU cores
    memory: 3         # GiB
    diskSize: 50      # GiB

Lima workstations do not require a providerConfig section. Resources (cpu, memory, diskSize) control the VM sizing directly.

Example

# lima-workstation.yaml
# Supported OS: ubuntu-24.04, debian-13
apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-local-dev
  labels:
    team: platform
spec:
  os:
    id: ubuntu-24.04
  provider: lima
  resources:
    cpu: 4
    memory: 3
    diskSize: 50

Additional fields for fine-grained settings such as network configuration and mount options are available but not yet documented.

AWS

The aws provider creates EC2 instances in your AWS account. werkr automates instance creation, SSH access, and port forwarding.

Platform: macOS, Linux, Windows.
Availability: Paid tiers only.

Provider Config

spec:
  provider: aws
  providerConfig:
    region: <string>            # AWS region (e.g., us-east-1)
    machineType: <string>       # EC2 instance type (e.g., t2.micro, t3.medium)
    securityGroupId: <string>   # Optional: pre-existing security group ID
  resources:
    diskSize: <number>          # EBS volume size in GiB

If securityGroupId is not specified, werkr auto-creates a werkr-ssh security group in the default VPC. If machineType is omitted, it defaults to t3.medium.

Example

# aws-workstation.yaml
# Supported OS: ubuntu-24.04, debian-13
apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-aws-dev
  labels:
    team: platform
spec:
  os:
    id: ubuntu-24.04
  provider: aws
  providerConfig:
    region: us-east-1
    machineType: t2.micro
  resources:
    diskSize: 20

Additional fields for security, access control, and fine-grained instance settings (VPC, subnet, IAM instance profiles) are available but not yet documented, or coming soon.

Azure

The azure provider creates VMs in your Azure subscription. werkr manages the full lifecycle including SSH access and port forwarding.

Platform: macOS, Linux, Windows.
Availability: Paid tiers only.

Provider Config

spec:
  provider: azure
  providerConfig:
    subscriptionId: <string>    # Azure subscription ID (required)
    resourceGroup: <string>     # Resource group name (required, must exist)
    location: <string>          # Azure region (e.g., eastus, westus2)
    machineType: <string>       # VM size (e.g., Standard_B2s, Standard_D2s_v5)
  resources:
    diskSize: <number>          # Managed disk size in GiB

If machineType is omitted, it defaults to Standard_B2s. The resource group must be pre-created in your Azure subscription.

Example

# azure-workstation.yaml
apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-azure-dev
  labels:
    team: platform
spec:
  os:
    id: ubuntu-24.04
  provider: azure
  providerConfig:
    subscriptionId: "your-subscription-id"
    resourceGroup: "your-resource-group"
    location: eastus
    machineType: Standard_B2s
  resources:
    diskSize: 30

Additional fields for security, access control, and fine-grained VM settings (virtual network, NSG, managed identity) are available but not yet documented, or coming soon.

GCP

The gcp provider creates Compute Engine VMs in your GCP project. werkr handles instance creation, SSH access, and port forwarding.

Platform: macOS, Linux, Windows.
Availability: Paid tiers only.

Provider Config

spec:
  provider: gcp
  providerConfig:
    projectId: <string>               # GCP project ID
    region: <string>                   # GCP region (e.g., us-central1)
    machineType: <string>              # Machine type (e.g., n4-standard-4)
    diskType: <string>                 # Disk type (e.g., pd-balanced, pd-ssd)
    enableNestedVirtualization: <bool> # Run VMs inside the VM
  resources:
    diskSize: <number>                 # Persistent disk size in GiB

If projectId is omitted, the currently configured gcloud project is used. enableNestedVirtualization is useful for running Android emulators or VMs inside the workstation.

Example

# gcp-workstation.yaml
apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-gcp-dev
  labels:
    team: platform
spec:
  os:
    id: ubuntu-24.04
  provider: gcp
  providerConfig:
    projectId: "your-project-id"
    machineType: n4-standard-4
    region: us-central1
    diskType: pd-balanced
  resources:
    diskSize: 20

Additional fields for security, access control, and fine-grained instance settings (network, subnetwork, service accounts, labels) are available but not yet documented, or coming soon.