Teleport for Emacs

Introduction

Gravitational Teleport is an open-source access platform that facilitates secure access to remote servers, Kubernetes clusters, and databases. This Emacs package seamlessly integrates with the Teleport command line tool (tsh), providing a similar experience to accessing remote hosts via SSH.

Key features include TRAMP integration, which enables file editing on remote hosts and file manipulation using Dired. Moreover, it offers the capability to initiate remote terminal sessions. This package is designed to enhance your Emacs environment by leveraging the power of Gravitational Teleport.

Installation and configuration

This guide assumes that you have already installed the teleport CLI and tsh is in your PATH.

The package is available on MELPA. Install it by evaluating

(package-install 'teleport)

If installation succeeds, load the package:

(require 'teleport)
(teleport-tramp-add-method)
(add-to-list 'tramp-default-user-alist '("\\`tsh\\'" nil "root"))

Users of use-package can add this piece of code to their config:

(use-package teleport
  :init
  (teleport-tramp-add-method)
  (add-to-list 'tramp-default-user-alist
             '("\\`tsh\\'" nil "root"))

  ;; Commands from this keymap are called with `default-directory' set to the remote host when called from `teleport-list-nodes' mode.
  :bind (:map teleport-list-nodes-mode-map
              ("v" . vterm)
              ("t" . term)
              ("d" . dired)))

List of teleport nodes

You can list all connected Teleport nodes by calling teleport-list-nodes command. It opens a new buffer with a table of connected nodes and their labels.

teleport-list-mode inherits its key bindings from Tabulated List Mode and adds a few mode specific bindings:

Key	Action
k	Hide current column
r	Un-hide all hidden columns
m	Mark node under cursor
u	Un-mark node under cursor
g	Update the buffer without fetching list of nodes
G	Fetch list of nodes again and update the buffer
i	Copy UUID of marked nods or the node under cursor
c	Open customize interface to customize hidden labels
/ p	Add a filter. All nodes with field not matching the regexp are removed
/ r	Reset the filers

Switching between teleport clusters

If you work with multiple different teleport clusters (e.g. work & personal) you could swithch between them using teleport-switch-to-cluster.

Running commands

When a command is invoked in teleport-list-nodes-mode, the mode checks if the commands exist in the teleport-list-nodes-mode-map and sets the default-directory to point to the node at point. As a result, most commands will be executed locally, and only those added to the mode keymap are executed on the remote host. This prevents Emacs from unnecessarily accessing the remote host when you call unrelated commands, such as switch-buffer.

Running shell commands

Nodes could be marked by pressing m and unmarked with u. Then teleport-list-nodes-mode--do-shell-command could be used to run the same command on all of the marked nodes. If no nodes marked, run the command for the nod under cursor. For each marked node a new buffer is created. For how to organise the buffers see [Window configuration](#window-configuration).

Configuring per-host logins

When running commands on remote hosts, teleport.el logins with user returned by `(tramp-find-user)`. You could configure it to use a specific user for a specific host. Assuming you want to login in hosts lucky-onyx and rainbow-smooch with user caramelhooves:

(add-to-list 'tramp-default-user-alist
             `(,(format "\\`%s\\'" teleport-tramp-method)
               "\\`\\(lucky-onyx\\|rainbow-smooch\\)\\'" "caramelhooves"))

Integration with other packages

The usefulness of this package is greatly enhanced by its integration with other Emacs packages.

Vterm

Vterm allows you to open a shell on the remote system directly from teleport-list-nodes-mode.

Under normal circumstances, no additional integration is required - it just works. However, if the remote host does not have the same shell as your local host, you may need to configure the shell to be used. If you encounter an issue where the vterm session opens and then immediately closes, consider adding this snippet to your configuration:

(with-eval-after-load 'vterm
    (add-to-list 'vterm-tramp-shells `(,teleport-tramp-method "/bin/bash")))

Dired-rsync

Dired-rsync is a fantastic package for efficiently and asynchronously copying files to and from remote hosts. With minor adjustments it could be configured to run over teleport:

(with-eval-after-load 'dired-rsync
  (defun teleport--is-file-on-teleport (filename)
    (when (tramp-tramp-file-p filename)
        (with-parsed-tramp-file-name filename v
          (string= v-method teleport-tramp-method))))

  (defun teleport-rsync-advice (orig-func sfiles dest)
    (if (or (teleport--is-file-on-teleport (car sfiles)) (teleport--is-file-on-teleport dest))
        (let ((dired-rsync-options (format "%s %s" dired-rsync-options "-e \"tsh ssh\"")))
          (funcall orig-func sfiles dest))
      (funcall orig-func sfiles dest)))
  (advice-add 'dired-rsync--remote-to-from-local-cmd :around #'teleport-rsync-advice))

Window configuration

teleport-list-nodes-mode--do-shell-command could create a lot of new buffers, they could be managed based on their name which is controlled by teleport-shell-command-buffer-name.

Create a new frame for each buffer

(setq display-buffer-alist '(("^\\*Teleport Shell Command Output: .*" display-buffer-pop-up-frame)))

If you are using Doom Emacs set-popup could be employed.

(set-popup-rule! "^\\*Teleport Shell Command Output"
  :side 'bottom
  :modeline t
  :size 0.25
  :actions '(display-buffer-in-side-window)
  :select nil
  :quit nil
  :ttl t)