Using Teleconsole

Quick Start

Lets say you are stuck configuring something on a Linux box behind NAT. You want to invite your friend to help you. Simply type teleconsole in your terminal:

$ teleconsole
Requesting a disposable SSH proxy for you...
Checking status of the SSH tunnel...

Your Teleconsole ID: 4bc2b5138360d343379b9043083c48eb7084c3b8
WebUI for this session:

Teleconsole will launch a new shell session and print the unique session ID which you need to share with your friend. Your friend can join in either by clicking on a link, or by typing:

$ teleconsole join 4bc2b5138360d343379b9043083c48eb7084c3b8

… and now you are both using the same terminal session running on your machine, even if both of you are on separate networks separated by NAT.


Please understand that by running teleconsole you are virtually giving the keyboard to anyone who knows the session URL. We made session IDs sufficiently hard to guess, but you are still running an SSH server accessible via public Internet during the Teleconsole session.

Secure Sessions

Teleconsole also allows you to share sessions only with specific people. This is more secure than default anonymous sessions.

To invite a specific Github user:

$ teleconsole -i kontsevoy

Teleconsole will make an API call to Github, will request the public key of kontsevoy and will configure your session to only let kontsevoy in and nobody else. This way even if someone steals the session ID, they will not be able to join because they don’t have the private part of the key, only “kontsevoy” has that.

Similarly, if you do not want to rely on Github, you can invite an owner of a public SSH key:

$ teleconsole -i

Kudos to Teleconsole users for suggesting this feature.

Ending the Session

When you’re done with the session, make sure to close it (stop teleconsole process) either by typing exit in the terminal or simply closing it. When Teleconsole exits, the outbound SSH tunnel is closed and your machine is no longer accessible.

Port Forwarding

Teleconsole also makes it easy for you to setup port forwarding as part of a session, thereby allowing your friends to access any TCP port running on your machine. Let’s say you are developing a web application and it is currently running on your http://localhost:5000. You can make it accessible by friends if you forward port 5000 when you initiate a new session:

$ teleconsole -f localhost:5000

When your friends join this session, they will see something like this:

$ teleconsole join 4bc2b5138360d343379b9043083c48eb7084c3b8
ATTENTION: elliot has invited you to access port 5000 on their machine via localhost:9000

So now they can open http://localhost:9000 in their browser to access your application.

Bear in mind, Teleconsole is just an SSH server, this means your friend can request port forwarding without your help, just like a regular SSH client would:

$ teleconsole -f 9000:localhost:5000 join 4bc2b5138360d343379b9043083c48eb7084c3b8

In fact, you can forward remote ports too. This command will allow a remote party to visit through your computer:

$ teleconsole -f join 4bc2b5138360d343379b9043083c48eb7084c3b8

Using Private Proxies

Some people may be uncomfortable using a publicly accessible SSH proxy on They can do the same thing by setting up a Teleport SSH bastion on their own server.

In fact, Teleport supports many more features, including session recording and replay, secure file copy (scp) and is compatible with the OpenSSH clients.

Follow these steps to set this up:

  1. Install and Configure a Teleport proxy server.
  2. Create user accounts in Teleport for your colleagues.
  3. Add your machine to the Teleport cluster, basically this means the proxy and your machine will trust each other.
  4. Launch SSH server on localhost: teleport --proxy=<your-server> --role=node start
  5. Launch tsh --proxy=<your-server> ssh localhost
  6. Share the session with your colleagues who also have accounts on the Teleport proxy.

For convenience, you can create a tiny bash script (or even a bash alias) which combines steps 4 and 5 into a single command, you can even call it teleconsole :)