The SSH card

Make an app that people use over SSH! Instead of opening a website, they type one command into their terminal, and your app shows up right there:

ssh yourapp.example.com

Nobody has to install anything, since pretty much every computer already comes with ssh.

Wait, what’s SSH?

SSH (short for Secure Shell) is how people log in to other computers over the internet. Usually, you connect to a server and get a shell, where you can type commands. But the server doesn’t have to give you a shell! It can run any program it wants and hook it up to your terminal instead. That program is what you’re making.

Try a few of these to see what’s possible:

• ssh terminal.shop sells real coffee, right from your terminal.
• ssh sshtron.zachlatta.com is a multiplayer Tron game made by Zach Latta, who started Hack Club!
• ssh chat.shazow.net is a whole chat room.

What counts

An app that runs on your server, that people use through an SSH connection. A game, a chat room, a guestbook, a tiny shop, a BBS, a portfolio you browse with the arrow keys…

A regular command line tool that people download and run on their own computer doesn’t count. It has to be something we connect to!

The easiest thing that counts

A guestbook: connect, read the last few messages, leave one of your own.

Wish, a Go library by Charm, lets you write an SSH server in a few lines, without any real shell or user accounts anywhere near it. Pair it with Bubble Tea (also by Charm) for the interface, and you get a proper terminal app with arrow keys and colours. Their examples folder has working apps you can start from.

Not a Go person? asyncssh for Python, ssh2 for Node.js and russh for Rust can all run an SSH server too.

Putting it online

Your app needs a computer that’s always on and that anyone can reach. Hack Club’s Nest gives teenagers a free Linux server, which is exactly what you need here! Ask in #nest if you get stuck. Any cheap VPS works too.

A few things that’ll save you a headache:

• Use a different port, like 2222, so your app doesn’t fight with the server’s real SSH on port 22. People then connect with ssh -p 2222 yourapp.example.com.
• Keep your host key. The first time someone connects, their computer remembers your server’s key. If your app makes a new one every time it starts, everyone gets a scary “REMOTE HOST IDENTIFICATION HAS CHANGED!” warning. Generate it once and save it to a file.
• Let everyone in. Don’t ask people for a password. Most libraries can accept anyone, and if someone connects with an SSH key, that key is a free way to recognise them when they come back!
• Never hand out a real shell. Your app should be the only thing people can reach. Libraries like Wish make this easy, because there’s no shell in there to begin with.

Making it feel nice

• Handle resizing. Terminals come in every size, and SSH tells you when someone resizes their window. A layout that adapts (or at least stays centred) looks way more polished.
• Be careful with colours. Not every terminal supports full 24-bit colour. Lip Gloss (Charm again!) picks the closest colour the terminal can show.
• Make it multiplayer! Everyone’s connected to the same server, so letting people see each other is easier than you’d think. A shared chat, a shared drawing canvas, a game of snake where everyone is a snake…

A DEC VT100 terminal, from 1978. A lot of the escape codes your app sends to move the cursor around were made popular by this thing, and terminal apps still pretend to be one today! Photo by Jason Scott, CC BY 2.0, via Wikimedia Commons.

Shipping one

• Demo: the demo field needs a web link, so use your repo link (like hardware projects do), and put the exact ssh command, port and all, at the very top of your README and in your project’s description. Make sure your server’s actually running while we review!
• Screenshot: your app in a terminal.
• README: how to connect, what to do once you’re in, and how it works. A short recording made with asciinema or VHS is a great way to show it off.