iimatey

Aye, Aye Matey

Does the inky blackness of the termimal on your computer seem a bit dawnting? Then use iimatey to call on a trusted matey to explore it with you!

What is it?

iimatey is a shel script that ties together tmux, ttyd, and the coder/wgtunnel client.

You can run your own instance of tunneld , we run one at https://iimatey.sharing.io which we configure via sharingio/infra

Install iimatey

One line install with the iimatey-setup.sh setup script

curl -fsSL https://raw.githubusercontent.com/ii/matey/canon/iimatey-setup.sh | bash

Manual install

tunnel client

Compile yourself from go, or grab a precompiled release from: https://github.com/ii/wgtunnel/releases/tag/v0.1.14 and ensure it’s in your PATH

ttyd/tmux on ubuntu

apt-get install -y ttyd tmux

ttyd/tmux on macos

first install brew, then:

brew install ttyd tmux

Run iimatey

get a sharable url to a local terminal

iimatey start

tmux session exists!
ttyd logs are available in /Users/hh/.config/iimatey/ttyd.log
tunnel logs are available in /Users/hh/.config/iimatey/ttyd.log
Connect to tmux locally via:
tmux -L ii at
[2023/03/22 05:34:47:5174] N: ttyd 1.7.3 (libwebsockets 4.3.2-unknown)
[2023/03/22 05:34:47:5179] N: tty configuration:
[2023/03/22 05:34:47:5179] N:   start command: tmux -L ii at
[2023/03/22 05:34:47:5179] N:   close signal: SIGHUP (1)
[2023/03/22 05:34:47:5179] N:   terminal type: xterm-256color
hh@Max iimatey % [2023/03/22 05:34:47:5547] N:    /opt/homebrew/Cellar/libwebsockets/4.3.2/lib/libwebsockets-evlib_uv.dylib
[2023/03/22 05:34:47:5548] N: lws_create_context: LWS: 4.3.2-unknown, NET CLI SRV H1 H2 WS ConMon IPV6-off
[2023/03/22 05:34:47:5549] N: elops_init_pt_uv:  Using foreign event loop...
[2023/03/22 05:34:47:5550] N: __lws_lc_tag:  ++ [wsi|0|pipe] (1)
[2023/03/22 05:34:47:5552] N: __lws_lc_tag:  ++ [vh|0|default||54321] (1)
[2023/03/22 05:34:47:5578] N: [vh|0|default||54321]: lws_socket_bind: source ads 0.0.0.0
[2023/03/22 05:34:47:5578] N: __lws_lc_tag:  ++ [wsi|1|listen|default||54321] (2)
[2023/03/22 05:34:47:5578] N:  Listening on port: 54321
Tunnel is ready. You can now connect to one of the following URLs:
  - https://656n2rc5uc81a.try.ii.nz
  - https://fcca314d716d85f310159675dc4bdf22.try.ii.nz

iimatey connect

iimatey status

terminal tty client :depau/ttyc depau/ttyc

A real terminal client for a ttyd/iimatey share URL — no browser needed. iimatey-setup.sh installs it (pinned release, see ttyc-v0.4), and iimatey itself now runs it for you whenever the first argument looks like a URL:

iimatey https://dg5srp8e9gsj6.try.sharing.io

(equivalent to running ttyc -U https://dg5srp8e9gsj6.try.sharing.io directly, if you’d rather call it yourself or pass its other flags — auth, reconnect backoff, etc — see ttyc --help.)

Note: license is GPLv3 (depau/ttyc) — installed as a separate pinned-release binary alongside ttyd/tunnel, never vendored/linked into this repo.

probe: is my share actually writable?

iimatey probe [URL] (or iimatey-probe directly) proves a share is up AND writable end to end: it speaks ttyd’s websocket protocol itself (python3 stdlib only, no packages), types one marker echo into the shared terminal, and checks the echo comes back. No URL means the local ttyd on localhost:7681; pass your share URL to test the whole path through the tunnel.

iimatey probe                                       # local ttyd
iimatey probe https://dg5srp8e9gsj6.try.sharing.io  # full path via tunnel

Exit 0: writable AND a padded ~1300B echo survives both directions. Exit 2: connects and streams output but even a small typed marker never echoes — a read-only server or a wedged connection. Exit 4: small frames pass but the padded echo vanishes — an MTU-shaped blackhole on the tunnel path (check the sharing host’s interface/path MTU; classic on WSL and double-NAT links). Exit 1: can’t connect at all. It exists because a single wedged websocket in a client is indistinguishable from “read-only”, and once got a healthy stack mis-diagnosed as a ttyc/ttyd protocol incompatibility; the probe answers which side is broken in seconds.

coder

coder server --wg-tunnel-host try.sharing.io

Here is the build from src:

coder server --wg-tunnel-host try.ii.nz

Coder v0.19.2-devel+c9014293 - Your Self-Hosted Remote Development Platform
Using built-in PostgreSQL (/Users/hh/Library/Application Support/coderv2/postgres)
Started HTTP listener at http://127.0.0.1:3000
Opening tunnel so workspaces can connect to your deployment. For production scenarios, specify an external access URL

View the Web UI: https://q1bn1bs94rnrm.try.ii.nz

Architecture

How iimatey works (ttyd + tunnel + tunneld): docs/architecture.md.