SSH Keys

werkr provides transparent SSH agent forwarding to workstations. When you define an SSHKey resource, werkr loads the key into its SSH agent and forwards it to connected workstations. This means you can use your local SSH keys (e.g., for Git operations) inside remote environments without copying private keys.

SSH keys are currently the primary way to give workstations access to private Git repositories and remote hosts. Other means of providing and injecting credentials are coming soon.

API Definition

apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: <string>
spec:
  path: <string>         # Path to the private key file (supports ~)
  selector:               # Optional: target specific workstations
    matchLabels:
      <key>: <value>

Basic Usage

By default, an SSH key with no selector is available to all workstations.

# ssh-keys.yaml
apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: id-ed25519
spec:
  path: ~/.ssh/id_ed25519
---
apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: id-rsa
spec:
  path: ~/.ssh/id_rsa

wer apply -f ssh-keys.yaml

Once applied, the keys are forwarded via the SSH agent to every running workstation. Inside the workstation, tools like git and ssh use the forwarded keys automatically - no additional configuration needed.

Targeting Specific Workstations

Use a selector to restrict which workstations a key is forwarded to. This is useful when different projects or teams use different deploy keys or personal keys for different Git repositories.

# A deploy key only for workstations with the "project: api" label
apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: deploy-key-api
spec:
  path: ~/.ssh/id_deploy_api
  selector:
    matchLabels:
      project: api

This key will only be forwarded to workstations that have the label project: api. Other workstations will not see it.

How It Works

werkr runs its own SSH agent and loads your configured keys into it. The agent is forwarded to workstations automatically - this happens independently of any wer shell or wer tmux sessions. Inside the workstation, werkr creates a ~/.ssh-auth-sock symlink pointing to the agent socket and a ~/.ssh-agent helper script that exports the required environment variables. This script is loaded via /etc/profile.d, so every shell session has access to the forwarded keys out of the box.

Any tool that uses SSH (Git, scp, ssh) can authenticate using your local keys without the private key ever leaving your machine. You can verify this inside a workstation by running ssh-add -l to list the keys available in the agent.

Adding or removing SSHKey resources takes effect on the fly - no restart of the workstation or reconnection is required.

Multiple Keys

You can define as many SSH keys as needed. All matching keys are loaded into the agent simultaneously. This is useful for setups where you have separate keys for GitHub, GitLab, internal hosts, etc.

apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: github
spec:
  path: ~/.ssh/id_github
---
apiVersion: werkr.dev/v1alpha1
kind: SSHKey
metadata:
  name: gitlab-deploy
spec:
  path: ~/.ssh/id_gitlab_deploy
  selector:
    matchLabels:
      gitlab: "true"

Common Operations

# Apply SSH keys
wer apply -f ssh-keys.yaml

# List SSH keys
wer get sshkeys

# View a specific key
wer get sshkey id-ed25519

# Edit an SSH key
wer edit sshkey id-ed25519

# Delete an SSH key
wer delete sshkey id-rsa

# Copy an SSH key as a starting point for a new one
wer copy sshkey id-ed25519 --name id-deploy