Labels

Labels are key-value metadata attached to tunnels. They are the primary discovery mechanism for automation, inventory, and operational selection. A tunnel name can remain useful for a single resource, but labels are the structure that makes tunnel fleets searchable and composable across environments.

This matters especially in deployments where the edge allocates hostnames dynamically, where services are intentionally not pinned to a single public endpoint, or where private tunnels are consumed only through native rstream clients. In those cases, labels provide the stable identifier that connects tunnel state back to application state, device identity, ownership, or environment.

Labels are also the shared selection surface across the raw engine APIs, signaling, the CLI, and fine-grained token scopes. If you are trying to make a multi-resource or multi-tenant integration coherent, labels are usually the first thing to model well.

Setting labels

From the CLI, labels are attached at tunnel creation time using repeated --label key=value values:

rstream forward 8080 \
  --name api-prod-01 \
  --label service=api \
  --label env=prod \
  --label owner=platform

Declarative sources support the same model. In YAML, labels are defined under tunnel.labels. In Docker mode, labels use the rstream.tunnel.<name>.label.<k> pattern.

tunnels:
  ssh:
    forward: 22
    name: ssh-prod-01
    publish: false
    labels:
      service: ssh
      env: prod
      role: admin

The label set remains application-defined. Keys such as service, env, role, site, device, or owner are common because they map cleanly to operational workflows, but rstream does not impose a fixed taxonomy.

Labels as selection keys

Labels are used consistently across the engine list APIs, the signaling stream, the CLI, and the SDKs. Because those APIs are already project-scoped, labels become the main selection surface for inventory and for real-time automation inside a project.

For inventory, the CLI can filter tunnel lists directly:

rstream tunnel list --filter 'labels.service=ssh,labels.env=prod'

For real-time workflows, the same labels can be applied to the signaling stream:

rstream events \
  --transport websocket \
  --tunnel-filter 'labels.service=ssh,labels.env=prod'

This separation is operationally useful. The list APIs describe what exists now, while the signaling stream describes what exists now and what changes next. Labels remain the common selection surface in both cases.

Managed labels

Tunnels created by rstream run are marked with managed labels. The reconciler applies rstream.managed-by=run and also records the source as rstream.source=apply or rstream.source=docker depending on the mode. These labels make it possible to distinguish reconciled tunnels from manually created tunnels during debugging and automation.

Labels and fine-grained tokens

Fine-grained token scopes can restrict which labels a token is allowed to use when creating tunnels and which labeled tunnels are visible or connectable to a token. This enables controlled delegation in multi-tenant or untrusted client environments.

For the surrounding API model, see APIs. For the real-time selection model built on the same labels, see Signaling. For the permission model layered on top of labels, see Fine-Grained Tokens.