Connection Profiles

A connection profile is a YAML file that describes one or more tunnels. Running tela connect -profile <name> opens all of them in parallel with a single command, each reconnecting independently on failure.

Profiles live in ~/.tela/profiles/ (or %APPDATA%\tela\profiles\ on Windows). Each file is named <profile-name>.yaml.

A Minimal Profile

# ~/.tela/profiles/work.yaml
connections:
  - hub: wss://hub.example.com
    machine: dev-server
    services:
      - remote: 22

tela connect -profile work

This opens a tunnel to port 22 on dev-server and binds it on localhost:22, or on a fallback port if 22 is taken locally. Use tela status to see the bound address.

Multiple Connections

A profile can open tunnels to any number of machines across any number of hubs simultaneously:

connections:
  - hub: wss://hub.example.com
    machine: dev-server
    services:
      - remote: 22
      - remote: 5432

  - hub: wss://hub.example.com
    machine: build-server
    services:
      - remote: 22

  - hub: wss://other-hub.example.com
    machine: staging-db
    services:
      - name: postgres

When two machines expose the same port, the first to bind gets the native port and the others land on fallback ports. To make the layout predictable, give each service an explicit local: port (see below).

Tokens and Credentials

If a token is stored in the credential store for a hub (via tela login or tela pair), the profile does not need to include it. The token is looked up automatically.

To embed a token explicitly:

connections:
  - hub: wss://hub.example.com
    machine: barn
    token: ${MY_HUB_TOKEN}

Profile YAML supports environment variable expansion with ${VAR} syntax. This is useful for tokens in CI/CD environments where you do not want credentials in files on disk.

Specifying Services

Services can be identified by port number, by name, or with a local port override:

services:
  # By port number: connects remote port 22 to local port 22
  - remote: 22

  # By port number with a local override: useful when 22 is taken locally
  - remote: 22
    local: 2222

  # By service name: resolves the port from the hub's service registry
  - name: postgres

  # By service name with a local port override
  - name: rdp
    local: 13389

Each service binds a listener on 127.0.0.1 at its local port (which defaults to the remote port). If that port is already in use, the client falls back to the port plus 10000, then plus 10001, and so on, and prints the port it actually bound. A local: override makes the port explicit so you never depend on fallback behavior.

A path gateway on the agent appears to clients as a service named gateway and is selected the same way as any other named service.

Auto-Mounting File Shares

If machines in the profile have file sharing enabled, you can configure the profile to mount them as a local drive automatically when the profile connects:

connections:
  - hub: wss://hub.example.com
    machine: barn
    services:
      - remote: 22

mount:
  mount: T:        # drive letter on Windows, or a directory path on macOS/Linux
  auto: true       # mount automatically when the profile starts
  port: 18080      # WebDAV listen port (default 18080)

Managing Profiles

tela profile list               # list all profiles
tela profile show work          # print the contents of work.yaml
tela profile create staging     # create a new empty profile at ~/.tela/profiles/staging.yaml
tela profile delete old-work    # delete a profile

tela profile create writes a starter file with example comments. Edit it with any text editor.

DNS Names

tela dns hosts generates hosts-file entries for all machines in a profile. Each machine gets a stable loopback address derived from its hub URL and machine name, so the entries survive reconnects:

tela dns hosts
# Tela local names, generated by 'tela dns hosts'
# 127.88.12.34       barn.tela
# 127.88.56.78       dev-server.tela

Append the output to your hosts file to enable name-based access:

# Linux / macOS
tela dns hosts >> /etc/hosts

# Windows (run as Administrator)
tela dns hosts >> C:\Windows\System32\drivers\etc\hosts

The default suffix is .tela. Override it:

tela dns hosts -suffix local       # barn.local
tela dns hosts -suffix ""          # bare names: barn, dev-server
tela dns hosts -profile staging    # use a specific profile

After adding the entries, connect to a machine by name:

ssh user@barn.tela
psql -h dev-server.tela -U postgres

Two profile fields tune the generated addresses. The dns block sets the loopback prefix used for all machines in the profile, and a per-connection address: field overrides the derived address for one machine:

connections:
  - hub: wss://hub.example.com
    machine: barn
    address: 127.99.1.1      # fixed address for barn in 'tela dns hosts' output

dns:
  loopback_prefix: "127.88"  # prefix for derived addresses (default 127.88)

An address: override must be in the 127.0.0.0/8 range. Both fields affect only the hosts entries that tela dns hosts generates; they do not change the ports that tela connect binds.

Running a Profile as an OS Service

A profile can run as a persistent OS service that reconnects automatically after reboots and connection drops:

tela service install -config ~/.tela/profiles/work.yaml
tela service start

See Run Tela as an OS Service for the full setup.

Tela: The Complete Reference