Manifests

werkr uses a declarative, Kubernetes-inspired manifest format. You describe the desired state of your resources in YAML files, and werkr takes care of making it happen.

How It Works

When you run wer apply -f manifest.yaml, werkr stores the desired state and begins reconciling it against the actual state of your infrastructure. Internally, werkr runs reconciler loops that continuously work toward eventual consistency - creating VMs, installing tools, setting up SSH access, and configuring port forwarding as needed.

This means you don't need to worry about ordering or manual steps. Define what you want, apply it, and werkr handles the rest.

Resource Types

werkr manages three resource types, all defined as YAML manifests:

  • Workstation - A development environment (local VM or cloud instance)
  • WorkstationConfig - Tools, packages, files, and settings to apply to matching workstations
  • SSHKey - SSH keys to forward to workstations for Git access and remote authentication

Manifest Structure

Every manifest follows the same structure, based on the Kubernetes API conventions: 

apiVersion: werkr.dev/v1alpha1
kind: <Workstation | WorkstationConfig | SSHKey>
metadata:
  name: <string>        # Unique name for the resource
  labels:                 # Optional key-value pairs (used for selector matching)
    <key>: <value>
spec:
  ...                     # Resource-specific configuration

Multiple Resources in One File

You can define multiple resources in a single YAML file, separated by ---. This is useful for keeping a workstation and its configuration together: 

# my-environment.yaml
apiVersion: werkr.dev/v1alpha1
kind: Workstation
metadata:
  name: my-dev-env
  labels:
    team: platform
spec:
  os:
    id: ubuntu-24.04
  provider: aws
  providerConfig:
    region: us-east-1
    machineType: t2.micro
  resources:
    diskSize: 20
---
apiVersion: werkr.dev/v1alpha1
kind: WorkstationConfig
metadata:
  name: platform-tools
spec:
  selector:
    matchLabels:
      team: platform
  portForward:
    autoForward: true
  contents:
    devtools:
      - docker
      - kubectl
      - kind
    packages:
      - tmux
---
apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: id-ed25519
spec:
  path: ~/.ssh/id_ed25519
# Apply everything at once
wer apply -f my-environment.yaml

Applying from Directories

You can also point wer apply at a directory to apply all YAML files in it: 

wer apply -f ./manifests/

Updating Resources

To update a resource, edit the manifest and run wer apply again. werkr detects the changes and reconciles the resource to match the new desired state. You can also use wer edit to modify a resource interactively, wer patch for targeted field updates from the command line, or wer copy to create a new resource from an existing blueprint.

Next Steps

Create your first local workstation or remote workstation, or explore the reference documentation for Configurations, SSH Keys, and Workstations.