#+title: 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!

#+HTML: <img src="https://user-images.githubusercontent.com/31331/227025347-29538023-f143-46bb-b365-854fae78709c.gif">

* What is it?

iimatey is a shel script that ties together [[https://github.com/tmux/tmux/wiki][tmux]], [[https://github.com/tsl0922/ttyd][ttyd]], and the [[https://github.com/coder/wgtunnel][coder/wgtunnel]] client.

You can run your own instance of tunneld , we run one at https://iimatey.sharing.io which we configure via [[https://github.com/sharingio/infra/tree/uk/apps/tunneld][sharingio/infra]]

* Install iimatey
** One line install with the [[https://github.com/ii/matey/blob/canon/iimatey-setup.sh][iimatey-setup.sh]] setup script
#+begin_src shell
curl -fsSL https://raw.githubusercontent.com/ii/matey/canon/iimatey-setup.sh | bash
#+end_src
** 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
#+begin_src shell
apt-get install -y ttyd tmux
#+end_src
*** ttyd/tmux on macos
first [[https://brew.sh][install brew]], then:
#+begin_src shell
brew install ttyd tmux
#+end_src
* Run iimatey
** get a sharable url to a local terminal
#+begin_src tmate :window iimatey
iimatey start
#+end_src
#+begin_example
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
#+end_example

#+begin_src shell
iimatey connect
#+end_src
#+begin_src shell
iimatey status
#+end_src

#+RESULTS:
#+begin_example
ii: 1 windows (created Wed Mar 22 06:11:00 2023) (attached)
0: zsh* (1 panes) [78x12] [layout ac1d,78x12,0,0,0] @0 (active)
Connect to tmux locally via:
tmux -L ii at
USAGE: iimatey [status|start|stop|connect]
#+end_example

** terminal tty client :[[https://github.com/depau/ttyc][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 [[https://github.com/depau/ttyc/releases/tag/ttyc-v0.4][ttyc-v0.4]]), and
~iimatey~ itself now runs it for you whenever the first argument looks like a
URL:

#+begin_src shell
iimatey https://dg5srp8e9gsj6.try.sharing.io
#+end_src

(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.

** share one role, not the whole stack

~iimatey share TARGET [NAME] [--rw]~ (alias: ~iimatey single~) shares ONE
tmux window — a single role/agent — while the rest of your stack stays
private. It links the target window into a dedicated viewer session with
tmux's prefix keys disabled (viewers cannot open windows, switch, or reach
a shell — keystrokes only ever go to the shared pane) and serves that via
its own ttyd+tunnel, independent of any full-session share.

#+begin_src shell
iimatey share infra:5 my-agent          # read-only: https://my-agent.sharing.io
iimatey share infra:5 my-agent --rw     # writable variant
iimatey shares                          # list active shares
iimatey unshare my-agent                # tear down (real window is untouched)
#+end_src

Read-only is the default and is enforced server-side (ttyd without
--writable). The shared window's geometry is frozen for the duration so a
small viewer window can't shrink your real display; restored on unshare.
TARGET can be a pane (stage:5.0) — it shares the containing window.

** 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.

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

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
#+begin_src shell
coder server --wg-tunnel-host try.sharing.io
#+end_src

Here is the build from src:
#+begin_src shell
coder server --wg-tunnel-host try.ii.nz
#+end_src

#+begin_example
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
#+end_example

* Architecture

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