client

Documentation

Overview

tela -- Tela Client

Purpose:

Connects to a Tela Hub via WebSocket, performs a WireGuard key exchange
with the target daemon, and establishes an encrypted L3 tunnel.

Subcommands:
  tela connect  -- connect to a machine (ad-hoc or via profile)
  tela machines -- list registered machines and their services
  tela services -- list services on a specific machine
  tela status   -- show hub status summary

Service selection (connect):
  -ports    -- comma-separated port numbers or local:remote pairs
  -services -- comma-separated service names (resolved via hub API)
  -profile  -- load a named connection profile (multiple hubs in parallel)

Environment variables (provide defaults so flags can be omitted):
  TELA_HUB      -- hub WebSocket URL
  TELA_MACHINE  -- target machine ID
  TELA_TOKEN    -- authentication token

Network (per-session addressing):

Agent IP:  10.77.{N}.1/32   (N = session index, 1-254)
Client IP: 10.77.{N}.2/32

tela files -- file sharing client.

Purpose:

Provides CLI access to file shares on connected machines. Requires
an active tela connect session. Communicates with the running tela
process via its control API, which proxies file share requests
through the WireGuard tunnel to telad port 17377.

Usage:

tela files ls -machine barn [path]
tela files get -machine barn <remote-path> [-o local-path]
tela files put -machine barn <local-path> [remote-name]
tela files rm -machine barn <remote-path>
tela files info -machine barn

Index

• func Connect(ctx context.Context, opts ConnectOptions) error
• func LoopbackAddr(prefix, hubURL, machine string) string
• func Main()
• func ResetForTesting()
• func SetVersion(v string)
• type BoundService
• type ConnectOptions
• type PortMapping

Functions

func Connect

func Connect(ctx context.Context, opts ConnectOptions) error

Connect opens a tela connect session against the given hub and machine, binds local listeners for the requested ports, and runs until ctx is cancelled. Mirrors what `tela connect -hub ... -machine ... -ports ...` does at the CLI, with reconnect backoff and the persistent-listener bridge.

This is the entry point the test harness in internal/teststack uses to push bytes through a real WireGuard tunnel without forking a subprocess. It returns nil on a clean ctx-driven shutdown; fatal session errors are returned wrapped in errFatal so the caller can distinguish them from a normal teardown.

func LoopbackAddr

func LoopbackAddr(prefix, hubURL, machine string) string

LoopbackAddr computes a deterministic loopback address for a hub+machine pair. The address is derived from SHA-256 so the same machine always gets the same address across sessions.

prefix  "127.88" (configurable, must be "127.{1-254}")
hubURL  hub WebSocket URL
machine machine name

Returns e.g. "127.88.42.17".

func Main

func Main()

Main is the entry point for the tela client binary. The cmd/tela shim calls this; tests do not -- they call Connect() directly with an in-process options struct.

func ResetForTesting

func ResetForTesting()

ResetForTesting wipes the package-level mutable state used by the client (stopCh, verbose flag, MTU override). Tests call this from teststack so consecutive runs do not see each other's state.

func SetVersion

func SetVersion(v string)

SetVersion overrides the package-level version string. Called once from the cmd/tela shim before Main() so log lines, registration messages, and the self-update channel comparison see the real linker-supplied version.

Types

type BoundService

type BoundService struct {
	Name     string `json:"name"`
	Local    int    `json:"local"`
	Remote   int    `json:"remote"`
	BindAddr string `json:"bindAddr"` // loopback address (e.g. "127.88.1.1")
	Machine  string `json:"machine"`
	Hub      string `json:"hub"`
}

BoundService describes a locally bound port forwarding a remote service.

type ConnectOptions

type ConnectOptions struct {
	HubURL    string
	MachineID string
	Token     string
	Ports     []PortMapping

	// Verbose enables per-message logging on this connection. Defaults
	// to the package-level verbose flag.
	Verbose bool
}

ConnectOptions tells Connect which hub and machine to dial and which ports to forward. Hub URL is required; Token is optional and falls back to the credstore lookup if empty.

type PortMapping

type PortMapping struct {
	LocalPort  uint16
	RemotePort uint16
}

PortMapping is one local-port → remote-port forwarding rule for a programmatic Connect call. Exported alias of the unexported portMapping type so the test harness can construct mappings without reaching into internals.