LocalBinding

A LocalBinding describes what this device forwards from a workstation: TCP ports and Unix sockets, statically or by auto-discovery. It also carries a service on this device into a workstation (reversePorts). It is the single interface for device-local forwarding, and it is never routed or synced: each device owns and writes its own.

apiVersion: core.ringleader.dev/v1
kind: LocalBinding

Most of the time you don’t author one directly: a workstation’s spec.defaultLocalBinding template makes the daemon seed a LocalBinding once, when the workstation first reaches Running (deletion is honored: it won’t re-create one you remove). If the workstation is shared with you instead of yours, the seed starts disabled, and rl binding enable turns it on. Author one explicitly when you want precise control.

Examples

Map a single port to a fixed host port, a one-line change. A per-port entry opts that port in on its own, so you don’t need forwardAll to forward just one:

spec:
  autoForward:
    ports: [{ port: 8080, localPort: 18080 }]   # workstation 8080 -> host 18080

Forward a workstation’s Docker socket to a fixed host path:

apiVersion: core.ringleader.dev/v1
kind: LocalBinding
metadata:
  name: docker
  namespace: dev
spec:
  enabled: true
  workstationSelector:
    matchName: my-box
  sockets:
    - remotePath: /var/run/docker.sock
      localPath: /tmp/ringleader-docker.sock

Auto-forward every listening port, with one exception and one override:

apiVersion: core.ringleader.dev/v1
kind: LocalBinding
metadata:
  name: runtime
  namespace: dev
spec:
  enabled: true
  workstationSelector:
    matchLabels:
      app: web
  autoForward:
    forwardAll: true
    ports:
      - port: 9999
        enabled: false        # exclude this discovered port
      - port: 80
        localPort: 8080       # override the host port
  urlForward:
    enabled: true
    open: false               # record opened URLs; don't auto-launch

Use a model server running on your Mac from inside a workstation. The workstation reaches it at its own 127.0.0.1:11434:

apiVersion: core.ringleader.dev/v1
kind: LocalBinding
metadata:
  name: ollama
  namespace: dev
spec:
  workstationSelector:
    matchName: my-box
  reversePorts:
    - localPort: 11434        # the service on this device

Spec fields

Provide exactly one of workstationSelector.matchName or matchLabels.

reversePorts works on every provider the daemon connects to, cloud workstations included, for as long as the daemon holds its connection. It never reaches a workstation someone else shares with you, and a workstation’s defaultLocalBinding template cannot declare it: only this device’s owner decides which of its services a workstation may reach.

portOffset shifts only the 1:1 auto-forwards (a workstation port with no explicit localPort override); static ports[] and per-port localPort values are left absolute. If a shifted host port would fall outside the valid 1–65535 range, the offset is skipped for that one port (it forwards 1:1) rather than wrapping around, so a large offset never lands a high workstation port on 0 or a privileged low port.

Status fields

The daemon writes these per-device.

status.message is derived from the same computation as the Ready condition, so the headline and the condition can never disagree. Read the condition’s own message for the per-aspect detail.

Conflict handling

When two bindings name the same host port, the daemon resolves it deterministically (first-wins by workstation [namespace, name], then binding [namespace, name]) and records the loser in status.dropped with a reason. It is never silent. Inspect the live picture with rl binding show.