Labels

Labels are key-value metadata attached to tunnels. They are designed for automation: applications and operators can tag tunnels with identifiers and then discover or filter tunnels through APIs and signaling streams.

Labels are not limited to human-readable names. They can encode ownership, environment, device identity, or application-level routing information. In systems where tunnel endpoints are dynamic, labels provide a stable handle for mapping tunnel state back to application state.

Setting labels

From the CLI, labels can be attached at tunnel creation time using repeated --label key=value values.

Declarative tunnel sources support labels as well. In YAML, labels are defined as a map under tunnel.labels. In Docker mode, labels are defined using the rstream.tunnel.<name>.label.<k> pattern.

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.