tunshell: a shell into a CI runner you could not otherwise reach

The problem is a machine you cannot SSH into

Tunshell is described as a simple and secure method to remote shell into ephemeral environments such as deployment pipelines or serverless functions, and the README is careful to say it is not an SSH replacement. The Why section asks the same question a reader would ask, why would I use this over my well-established SSH client, and answers it plainly: you would not. The use case is quick, ad-hoc remote access to hosts which you may not have SSH access to, or even the ability to install an SSH daemon at all. That last clause is the real one. A container image for a Lambda function has no sshd, no systemd and often no package manager, so the only way in is to run something yourself, and that is what the client binary is. The client is statically linked and pre-compiled, so it can be installed by downloading it with a one-liner script, which is what makes the whole approach work in environments where you cannot compile anything.

Three components, and the website is the control plane

The architecture is three parts, and the repository mirrors that layout. The relay server, in tunshell-server, is a server which coordinates with clients to establish connectivity. The client binary, in tunshell-client, is a portable binary acting as a shell server or a client. The website, in the website directory, is the user interface for configuring a remote shell session with the relay server and for providing the install scripts for the client. The workspace manifest lists tunshell-shared, tunshell-client, tunshell-server and tunshell-tests as members, and the repository also carries a Cross.toml, which is the cross-compilation configuration, and an aws/ directory alongside the scripts. The shared crate is where the protocol types live, which is the usual arrangement for a client and server pair that must agree exactly on the wire format.

A session is two install scripts and four pieces of state

You start at tunshell.com, where you generate a session which represents a remote shell connection from one client to another, and for each session the website generates one install script for each side. Each script embeds four things, and the README walks through them. The installer script URL points to a script which installs the client binary on the executing machine, and these scripts detect the host's OS and CPU architecture to download the correct pre-compiled executable. The mode argument is target mode (T) or local mode (L), instructing the client to operate as a shell server or a client respectively. The session keys are a pair of random strings generated by the relay server, passed back on initialisation, and once a pair of clients have sent corresponding keys the relay server begins establishing connectivity between them. The encryption secret is generated locally using javascript on the website and is used to derive a unique encryption key for the data transmitted between the two clients. The relay coordinates; it does not decrypt.

Three networking paths, tried in order

After both clients have validated their session keys with the relay, the connection is attempted in three ways, in a stated priority order. First, TCP: the clients try to connect to the peer directly over TCP, which the README notes will likely fail if both clients are behind a firewall or NAT device. Second, UDP: the implementation contains a thin TCP-like protocol built on UDP, and the README says that in some cases this can help establish a direct connection if at least one of the clients is behind a more permissive NAT device. Third, relayed: when no direct connection succeeds, the clients fall back to proxying data through the relay server, which traffics packets between the clients using the existing TLS connections each of them initiated. The relayed path is also what a browser client uses, in which case a Web Socket is used between the client and the relay server on top of TLS. The design detail worth noting is that the relay never terminates the encrypted session, it forwards bytes inside TLS tunnels the clients already established.

A fallback shell for environments with no PTY

The in-built shell exists because of a specific environment limitation. In some restricted environments the client will not have permission to allocate a PTY, which means running the native shell in an interactive session is not going to be possible. The client has a bare-bones, and the README puts it in parentheses as incomplete, implementation of a VT100-style shell which does not require a PTY and is used as a fallback in such cases. The README then says this is still work in progress. This is the sharpest limitation in the tool, because the environments tunshell is most useful for are the most restricted ones. You can get a shell into an AWS Lambda function, but the shell you get may not be a full interactive shell with job control, and the README does not describe which features are missing. If your debugging needs a real interactive terminal, test this on the specific platform before assuming it works.

The author documents the risks in the README itself

The Security Considerations section is unusually blunt, and it is the part to read first. The README says that before using tunshell it is important to understand the inherent risks, and that the nature of the application and installation method should trigger alarm bells in any developer's head given we are exposing shell access over a network. It then concedes that although a lot of thought has gone into limiting the attack surface there is still a lot of room for improvement. The installation method relies on the execution of a third party script and binary on the host machine, so if those were to be compromised so would your host, and it is critical that these are produced and delivered in a secure and transparent process. The supply chain answer given is that the artifacts are generated directly from the source in this repository, stored in AWS S3 and served via a CloudFront CDN. The README also has an Unsavory Use-cases section, noting the tool could be used as an exploitation tool to gain unauthorized access to remote hosts, and that the author hopes it is not misused, with the free service discontinued if it appears to be helping malicious actors.

MIT licensed, quiet for a while, with a security file

The licence is MIT with the LICENSE file at the repository root, and there is a separate SECURITY.md alongside a TODO.md, which is the right pairing for a tool whose whole surface area is network-facing shell access. The repository is not archived and the last push was on 2026-07-05, which is more than three months before today, so the code is not being changed week to week at the moment. There are no GitHub releases, so there is no tagged artefact to pin and no release notes to read, and the version numbers in the binary are not something you can look up. The deployment surface is also narrow by design: a hosted service at tunshell.com, a client, and a relay. For an organisation with a policy against sending shell traffic through a third-party relay, the relay is the part to think about, and the README does not document a way to run the relay server yourself as part of a normal deployment, though the source for it is in the repository.

Editorial conclusion

Adopt tunshell when you need to debug a build that fails only in its CI environment and you have no SSH access to that machine, and you are willing to run a third-party install script on it. Do not adopt it as a general remote access tool for production hosts, because the author says so plainly and because the fallback shell is incomplete, and think twice before installing it anywhere you do not control. Before you commit, read SECURITY.md in the repository, check that your network permits the peer connection paths the tool tries in order, and remember that the last push was on 2026-07-05.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. TimeToogo/tunshell on GitHub