Before you start

Requirements

clawee is a client — it runs on top of burrowee, the transport that carries your connection to the remote box. You need two things:

• burrowee installed — get it at burrowee.com. clawee talks to the local burrowee daemon over a unix socket and will auto-start it when needed (it never replaces or supervises it).
• a paired gateway — your device must be bootstrapped against at least one burrowee gateway (see pairing below). Without a gateway binding there's no route, and clawee will tell you so.

Supported clients: macOS and Linux. A box that hosts sessions also runs claweed (the session broker).

Setup

Get running

Two components, each installed with a one-liner (fetched over TLS and signature-verified from release.clawee.org). On a fresh setup, install the daemon on each box that hosts sessions first, then the client on the machines you drive them from.

1. Install the daemon — boxes that host sessions
   $ curl -fsSL https://release.clawee.org/claweed/install.sh | sh copy

   $ claweed setup            # first run, as your own login: doctor --fix, then tenant status + knock/approve guidance

2. Install the client — your laptop / workstation
   $ curl -fsSL https://release.clawee.org/clawee/install.sh | sh copy

   If the install directory is not on your PATH, the installer says so and prints two blocks for your shell — Add it to this shell now: and Make it permanent: — with every path quoted; for fish the permanent step appends fish_add_path --global <dir> to ~/.config/fish/config.fish.

   The client installer also installs JetBrainsMono Nerd Font Mono for your user — the terminal's fallback font for the glyphs the clawee TUI draws — into ~/Library/Fonts on macOS or ${XDG_DATA_HOME:-~/.local/share}/fonts on Linux (then fc-cache). The faces are fetched at a pinned tag and installed only if every file matches its SHA256. It then says select "JetBrainsMono Nerd Font Mono" as your terminal's font; no terminal's settings are changed, and the summary's font line reads installed just now. It skips with one line: as root, font: skipped (root) — rerun without sudo to install the font for your user; in an ssh session, font: skipped — this is an ssh session; install JetBrainsMono Nerd Font where your terminal runs; when one is present, font: JetBrainsMono Nerd Font already installed; and with CLAWEE_NO_FONT=1, under CI or with no terminal. A fetch or checksum failure is a warning and never fails the install.

3. Bind to a gateway — the route

   In your burrowee console, mint a one-time blob + PIN, then on the client:

   $ burrowee bootstrap <blob> <pin>

   This is transport only — it carries no trust on its own.

4. Pair the device — trust

   Trust is separate from the route, and claweed setup does not create it — it reports your tenant's key state and names the two ways to enrol one (see setting up the daemon). For the first device on a host, the route setup itself prints is to knock from the new device (below) and approve it on the host, where you already have a login: claweed devices approve — no enrolled device needed, and (since claweed v0.2.16) no setup or tenant add needed first: the first knock is recorded even for a login with no tenant data yet. Or enrol it by hand before it ever knocks: copy the client's ~/.clawee/id_ed25519.pub across and run claweed auth @id_ed25519.pub there — see pairing a device for that walkthrough. Approving from another device is how every additional device pairs; it needs one already enrolled, so it is never the first step.

   On the new device, run clawee — an untrusted key can't open a session, so the picker opens as a pairing form instead. Press Enter on the pair row to send the knock:

   gateway   workshop (SHA256:a1b2c3d4)
   status    not paired
   key       SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   
   re-check (c) · re-send key (s) · relays (l) · quit (q)

   Then approve the pending fingerprint — on the host, or from a device that's already enrolled:

   $ claweed devices approve [<#>|<fp>] [--label <x>]   # on the host — works with none enrolled
   $ clawee devices approve [<#>|<fp>] [--label <x>]    # bare = first asking, #N = pending index

   The new device's form re-checks itself every 10 seconds and drops into the ordinary picker once the key is trusted.

5. Attach

   Back on the client, open the picker and attach:

   $ clawee

Where next

Where next

Once you're attached, here's the rest of the surface:

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.