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 to a deterministic loopback address. 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

Each connection gets its own deterministic loopback address. Services on different machines never share a local port.

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

When you specify name: gateway the gateway service is resolved the same way as any other named service.

Pinning a loopback address

By default each machine gets a deterministic loopback address derived from the hub URL and machine name. To fix a specific address instead:

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

The address must be in the 127.0.0.0/8 range.

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)

DNS name resolution

The dns block configures the loopback prefix used by tela dns hosts for this profile:

connections:
  - hub: wss://hub.example.com
    machine: barn

dns:
  loopback_prefix: "127.88"   # prefix for 'tela dns hosts' entries; does not affect port binding

See the DNS names section below for how to add machine names to your hosts file.

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 /etc/hosts entries for all machines in a profile, using their deterministic loopback addresses:

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

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.