Reference

Gateways

Each gateway can hold more than one OS user now — clawee scopes sessions and devices per (gateway, user) pair, not just per gateway. clawee groups what it reaches into boxes — one machine, however many burrowee relays and ssh hosts lead to it. Name a box, fall back to the chooser, or set friendly names; a box with no user added yet has nothing to attach as until you add one.

clawee [<user>@]<box>Attach on that box, as that user or its selected one. A box name, a fingerprint (or a unique prefix — 4+ hex for the local box) and local resolve alike, here and in every session address.

clawee gatewaysOpen the box chooser — every box you reach, its users, and the burrowee relay and ssh host for each (piped: the per-gateway session grouping).

clawee gateways add [user@]<gateway> [--user <user>]Add OS users to a gateway (--user repeats); the first ever added becomes its default.

clawee gateways use <fp|name> [<user>]Switch to that gateway — and optionally that user — then attach.

clawee gateways list [--json]Print the local box first — local <box name> <fp> <users> — then the burrowee gateways. --json prints [{name, fp, kind: local|burrowee|ssh, users, this_machine}].

clawee gateways name <fp|name> <short>Set a friendly short name for a gateway (- or empty clears it).

clawee gateways user <fp|name> add|rm <user>Add or remove a user known at that gateway (add also selects it).

gw is a short alias for gateways, and the old clawee gateway still works — clawee gw list and clawee gateways list are the same command. The local box's fingerprint comes from claweed's instance id, so it does not change for the life of the install; it reads fp unknown until the first authenticated hello.

With a single gateway, none of this shows — clawee goes straight to the picker. With more than one, bare clawee uses your last gateway or opens the chooser; press g in the picker to switch.

The chooser (titled Clawee Boxes) lists boxes in up to three sections: Local (💻 — this machine, when it runs claweed, under its own box name), Pinned (📌) and Remote (🌐). Five columns — BOX · USER · SESSIONS · BURROWEE · SSH. Each box lists its users beneath a + add user row; BURROWEE shows how many relays reach the box and the one it is dialled through, SSH how many hosts and the one in use (+ add host when there is none). A box with no burrowee gateway shows — there; the local box has neither column. The focused cell sits on a band, the selected box and user are yellow, and the focused column's heading lights up:

  BOX                USER         SESSIONS   BURROWEE                             SSH

💻 Local
  studio             + add user
▸                    admin        2

🌐 Remote
  alpha              + add user              (3) · wss://relay-a.example.net      (2) · 192.168.1.123:22
                     admin        3
                     deploy

  bravo              + add user              —                                    + add host
                     admin

Keys in the chooser:

↑↓Move between boxes and users.

←→Move between columns. A box with no burrowee skips that column; the local box stops at USER.

EnterConnect as the focused user — over burrowee when the box has a gateway, else over ssh (or, with no host yet, to the host list to add one). On + add user it adds a user; on + add host, a host.

b · sConnect over burrowee · over ssh, from any column. The local box has no ssh route and says so.

l · hOpen the box's relay list · its host list — a pick there is the chooser's pick.

iPin / unpin the box — pinned boxes get their own section above Remote. The local box cannot be pinned.

rSet the box's short name.

dDelete — the user under the cursor on the USER column, the box anywhere else. Asks first. Removing a user only forgets it on this machine; its device key stays approved on the host until you revoke it (devices). The local box cannot be deleted, only its users.

mMerge the box's burrowee gateway into another box — the one clawee suggests, or one you name — when both are the same machine.

gReload the gateways.

q · Ctrl+CFrom g in the picker: back, without switching (Esc too). From clawee gw or the launch screen: quit — Esc closes nothing there.

The bar reads burrowee (b) · ssh (s) · relays (l) · hosts (h); on clawee gw and the launch screen it ends in quit (q), and while a launch countdown is armed the countdown follows it. Under it, a tip line reads pin (i) · del (d) · name (r) · merge (m) · reload (g) · columns (←→). Devices live in the session picker (v).

Reference

Routes

A box is reached one of three ways: local (it is this machine), ssh, or burrowee. The chooser's Enter prefers burrowee when the box has a gateway; the headless session verbs try local, then ssh, then burrowee. The picker's identity line names the route in use (via local, via ssh, via burrowee); --ssh <host> and --burrowee force one.

clawee ssh add [user@]<host>[:port]Add an ssh route — no burrowee relay; ssh forwards to the remote claweed's socket (--socket <path> names it verbatim).

clawee ssh list · rm <host>List the ssh hosts and the socket each forwards to · remove one.

clawee ssh <host>Attach over that host.

The host is passed to ssh(1) verbatim, so a ~/.ssh/config alias carries its own user, port, key and ProxyJump. A host literally named add, list or rm needs a different alias there.

When a connection drops, clawee stays on the session: a reconnect box takes the bottom lines, says what is happening, and keeps retrying on the same relay. Its options are r change relay (on a burrowee route), d detach, q quit, and p re-pair when this device needs pairing again — ←/→ and ⏎, or the letter. Typing starts a draft in the composer and never loses it. A resume (clawee <box> -s <sid>) opens on the same connecting… box as a pick from the picker.

The box's status tracks the retries: reconnecting… (1 · retry <delay>) on the first, then switching carrier… (<n> · retry <delay>) from the second on. On a burrowee route every retry asks the relay for a fresh carrier, and while the relay looks for one the status reads finding a working carrier… (<n> · retry <delay>). A carrier the relay replaces while you are still connected is switched to silently — no box and no status change.

Reference

Client config upgrade

Upgrading is one-way. Once a v0.2.x clawee writes config.json or a session's meta.json in the multi-user schema, an older clawee binary refuses the file outright rather than silently misreading it — there is no downgrade path. Rolling a fleet back means rolling its config back with it. On the daemon side, the instance id lives in the system config root (moved there by the v0.2.0 migration ladder) and is an auth-challenge input: a regenerated value silently refuses every already-enrolled device. claweed never generates one on its own — only the installer's migration adopts it — so treat that file as load-bearing, not disposable.

Reference

CLI reference

Verbatim help pages for the gateways and ssh verbs, generated by clawee docs from the binary's own help renderer.

clawee gateways

gateways: interactive switch (bare), plus the scripting verbs (alias: gw)

clawee gateways — gateways: interactive switch (bare), plus the scripting verbs (alias: gw)

Usage:
  clawee gateways [<command>]

Commands:
  add                         add OS users to a gateway (the first ever added becomes its default)
         [user@]<gateway>
         [--user <user>]      an OS user to add (repeatable; the user@ prefix counts as one)
  use                         switch the active gateway (optionally picking the user), then attach
         <fp|name> [<user>]
  list                        print the local box (name, fp, users), then the burrowee matrix
                              gateways
         [--json]
  name                        set the gateway's local short-name ("-" or empty clears)
         <fp|name> <short>
  user                        grow or shrink the gateway's OS-user list
         add <user>           add the user to the gateway (and select it)
         rm <user>            remove the user (clears the selection if it pointed there)

Bare `clawee gateways` opens the interactive switch modal on a terminal, and
prints the per-gateway session grouping when piped. `clawee gateway` still works.

clawee gateways add

add OS users to a gateway (the first ever added becomes its default)

clawee gateways add — add OS users to a gateway (the first ever added becomes its default)

Usage:
  clawee gateways add [user@]<gateway> [flags]

  add
        [user@]<gateway>
        [--user <user>]    an OS user to add (repeatable; the user@ prefix counts as one)

clawee gateways use

switch the active gateway (optionally picking the user), then attach

clawee gateways use — switch the active gateway (optionally picking the user), then attach

Usage:
  clawee gateways use <fp|name> [<user>]

  use
        <fp|name> [<user>]

clawee gateways list

print the local box (name, fp, users), then the burrowee matrix gateways

clawee gateways list — print the local box (name, fp, users), then the burrowee matrix gateways

Usage:
  clawee gateways list [--json]

  list
         [--json]

The local row is `local <box name> <fp> <users>`; the fp is derived from the claweed
instance id, so it does not change for the life of the install (`fp unknown` until the first
authenticated hello). A box name, an fp (or a unique prefix, 4+ hex for the local box) and `local` resolve alike in
every address. --json prints [{name, fp, kind: local|burrowee|ssh, users, this_machine}].

clawee gateways name

set the gateway's local short-name ("-" or empty clears)

clawee gateways name — set the gateway's local short-name ("-" or empty clears)

Usage:
  clawee gateways name <fp|name> <short>

  name
         <fp|name> <short>

clawee gateways user

grow or shrink the gateway's OS-user list

clawee gateways user — grow or shrink the gateway's OS-user list

Usage:
  clawee gateways user <fp|name> add|rm <user>

  user
         add <user>   add the user to the gateway (and select it)
         rm <user>    remove the user (clears the selection if it pointed there)

clawee ssh

manage ssh-forwarded routes to a remote claweed (no burrowee relay)

clawee ssh — manage ssh-forwarded routes to a remote claweed (no burrowee relay)

Usage:
  clawee ssh <add|list|rm>

Commands:
  add                           add a new ssh route (an existing host is refused)
         [user@]<host>[:port]
         [--socket <path>]      path to the remote claweed socket, verbatim — overrides
                                route.DefaultRemoteSocket()
  list                          list configured ssh hosts and the remote socket each forwards to
  rm                            remove an ssh route
         <host>

The host is passed to ssh(1) verbatim, so a ~/.ssh/config alias carries its
own user, port, key and ProxyJump. `clawee ssh <host>` to select one is a
separate command. Sub-verbs win: a host literally named add, list or rm
cannot be typed directly here — those words always dispatch this verb — but
stays reachable by giving it a different alias in ~/.ssh/config.

clawee ssh add

add a new ssh route (an existing host is refused)

clawee ssh add — add a new ssh route (an existing host is refused)

Usage:
  clawee ssh add [user@]<host>[:port] [flags]

  add
        [user@]<host>[:port]
        [--socket <path>]      path to the remote claweed socket, verbatim — overrides
                               route.DefaultRemoteSocket()

clawee ssh list

list configured ssh hosts and the remote socket each forwards to

clawee ssh list — list configured ssh hosts and the remote socket each forwards to

Usage:
  clawee ssh list

clawee ssh rm

remove an ssh route

clawee ssh rm — remove an ssh route

Usage:
  clawee ssh rm <host>

  rm
       <host>

See the full generated references: clawee CLI reference · claweed CLI reference.

Docs synced 2026-10-17 against clawee v0.3.46 · claweed v0.3.29 — a partial pass over the guard-aware update and restart, the tab title that shows a session asking for you, and the installer exit codes, on top of the v0.3.42 catch-up. See docs_sync.json for what is not covered.