Configurations

A WorkstationConfig defines what tools, packages, files, and settings to apply to matching workstations. It uses label selectors for targeting and is independent of the underlying provider - the same configuration works across AWS, Azure, GCP, and Lima.

API Definition

apiVersion: werkr.dev/v1alpha1
kind: WorkstationConfig
metadata:
  name: <string>
spec:
  priority: <number>              # Order of application (higher = later, wins conflicts)
  selector:
    matchLabels:
      <key>: <value>             # Match workstations with these labels
  portForward:
    autoForward: <bool>           # Automatic port forwarding
    ports:
      - localPort: <number>
        remotePort: <number>
        remoteHost: <string>      # Default: localhost
  kubeconfig: <bool | string>     # Sync remote ~/.kube/config locally
  contents:
    packages:                      # System packages (apt)
      - <string>
    devtools:                      # Development tools
      - <string>                  # e.g., "docker", "kubectl", "kind"
    environment:                   # Environment variables
      <key>: <value>
    files:                         # Files to create
      - path: <string>
        content: <string>         # Inline content
        localFile: <string>       # Or read from a local file
        url: <string>             # Or download from URL
        mode: <string>            # Octal permissions (e.g., "0644")
        owner: <string>           # e.g., "root:root"
    scripts:                       # Scripts to run during provisioning
      - name: <string>
        inline: <string>          # Script content
        url: <string>             # Or download from URL
        runAs: <string>           # User to run as (default: root)
        failOnError: <bool>       # Stop provisioning on failure (default: false)
    defaultUser:                   # Primary user account
      username: <string>
      shell: <string>             # e.g., "/usr/bin/zsh"
      groups:
        - <string>

Label Selectors

The selector.matchLabels field determines which workstations this configuration applies to. A workstation must have all specified labels to match. An empty selector matches all workstations.

Example: Match by team

spec:
  selector:
    matchLabels:
      team: platform

Example: Match by multiple labels

spec:
  selector:
    matchLabels:
      team: platform
      env: dev

Devtools

The devtools field installs development tools on the workstation. You can optionally pin a version with =.

contents:
  devtools:
    - docker
    - kubectl
    - kubectl=1.28.0    # Pin to a specific version
    - kind
    - helm
    - go

Available Devtools

Name	Description	Version Pinning
`asdf`	asdf version manager for managing multiple language runtimes	Yes
`az`	Azure CLI	No (latest)
`claude`	Claude Code - Anthropic's AI coding assistant. Pair with `www-browser-remote` for browser-based authentication.	No (latest)
`docker`	Docker Engine, CLI, containerd, buildx, and compose plugins	No (latest)
`gcloud`	Google Cloud CLI	No (latest)
`gh`	GitHub CLI	Yes
`go`	Go programming language	Yes
`helm`	Helm - Kubernetes package manager	Yes
`kind`	kind - local Kubernetes clusters using Docker containers	Yes
`kubectl`	Kubernetes command-line tool	Yes
`terraform`	Terraform infrastructure-as-code tool	Yes
`www-browser-remote`	Registers werkr's browser forwarding as the system default browser. URLs opened inside the workstation (e.g., OAuth login flows) are forwarded to your local machine. Required for tools that use browser-based authentication.	No

System Packages

The packages field installs system packages using the OS package manager.

contents:
  packages:
    - tmux
    - vim
    - jq
    - curl

Port Forwarding

Port forwarding makes services running on the workstation accessible from your local machine.

Explicit Ports

Define specific port mappings to forward known services:

portForward:
  ports:
    - localPort: 8080
      remotePort: 8080
    - localPort: 3000    # Forward remote 3000 to local 3000
      remotePort: 3000
    - localPort: 5433    # Map remote Postgres to a different local port
      remotePort: 5432

Automatic Port Forwarding

With autoForward: true, werkr automatically detects ports that open on the workstation and forwards them to your local machine. When a port closes, the forwarding is removed. This means you don't need to know in advance which ports your services will use - werkr handles it dynamically.

portForward:
  autoForward: true

You can combine both - use autoForward for dynamic ports and explicit mappings when you need a specific local port:

portForward:
  autoForward: true
  ports:
    - localPort: 5433
      remotePort: 5432

OAuth and Browser-Based Authentication

Port forwarding enables tools that perform OAuth-based login (such as the claude CLI, gh auth login, or gcloud auth login) to work transparently inside workstations. The tool opens an authentication URL that launches in your local browser, and the OAuth callback is forwarded back to the workstation, completing the login flow without any manual steps.

Kubeconfig Sync

Sync the remote workstation's ~/.kube/config to your local machine, so you can use kubectl locally against a remote cluster.

# Sync to default ~/.kube/config
kubeconfig: true

# Sync to a custom path
kubeconfig: "~/kubeconfigs/remote.yaml"

Files

Create files on the workstation during provisioning. Content can be inline, read from a local file, or downloaded from a URL.

contents:
  files:
    - path: .gitconfig
      content: |
        [user]
          name = Developer
          email = dev@example.com
    - path: /etc/custom.conf
      localFile: ./configs/custom.conf
      mode: "0644"
      owner: "root:root"

Scripts

Run scripts during provisioning. Scripts run as root by default.

contents:
  scripts:
    - name: setup-project
      inline: |
        git clone https://github.com/org/repo.git /home/dev/repo
      runAs: dev
    - name: install-deps
      url: https://example.com/setup.sh
      failOnError: true

Environment Variables

Set environment variables that will be available in the workstation's default user shell.

contents:
  environment:
    EDITOR: vim
    GOPATH: /home/dev/go
    NODE_ENV: development

Configuration Layering

Multiple WorkstationConfigs can match a single workstation. They are merged in order of priority (lower first), with later configurations taking precedence for conflicting values. This enables layered configuration:

Base config (priority: 0) - Common tools for all workstations
Team config (priority: 10) - Team-specific tools
Project config (priority: 20) - Project-specific dependencies

Full Example

# platform-config.yaml
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
      - jq
    files:
      - path: .gitconfig
        content: |
          [user]
            name = Platform Engineer
            email = platform@example.com
    environment:
      EDITOR: vim

Common Operations

# Apply a configuration
wer apply -f config.yaml

# List configurations
wer get workstationconfigs

# View details
wer get workstationconfig platform-tools

# Edit
wer edit workstationconfig platform-tools

# Delete
wer delete workstationconfig platform-tools