clawee_ Home burrowee Install

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). Without a gateway binding there's no route, and clawee will tell you so.
Why burrowee? clawee deliberately owns no transport of its own. burrowee handles pairing, gateways, relays, and the encrypted tunnel; clawee focuses on the terminal — sessions, the picker, uploads, the composer. Learn more at burrowee.com.

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

Setup

Install

Both installers are fetched over TLS and signature-verified before anything executes (served from release.clawee.org).

Client — your laptop / workstation

$ curl -fsSL https://release.clawee.org/clawee/install.sh | sh

Daemon — boxes that host sessions

$ curl -fsSL https://release.clawee.org/claweed/install.sh | sh

Keep clawee current any time with:

$ clawee update            # shows the version gap; skips if current
$ clawee update --force    # reinstall the latest regardless

Setup

Pairing a device

Pairing happens in burrowee — it binds this device to a gateway. Get a one-time blob and PIN from your burrowee console, then: 

$ burrowee bootstrap <blob> <pin>

That gives clawee a route. On first connect, clawee presents its device key to the remote daemon. A brand-new key isn't trusted yet — it knocks, and you approve it from a device that's already enrolled: 

$ clawee devices            # list enrolled keys + pending knocks
$ clawee devices approve <fp>   # enroll a pending device key
If a connection is refused as pending approval, clawee status prints the exact clawee devices approve … line to run — no copying fingerprints by hand.

Daily use

Attaching

Run clawee with no arguments to open the session picker and attach. Flags tune the bare invocation:

claweeOpen the local session picker and attach.
clawee <gateway>Select a gateway by name, then pick a session (see gateways).
-rResume the most-recently-attached session.
-s <sid>Attach a remote pty session id directly.
-user <name>Gateway OS user to claim (default: $USER, or last-used).
-i <key>Private key to authenticate with (default: ssh-agent, then ~/.clawee/id_ed25519).
-socket <path>burrowee transport daemon socket (default: the burrowee default).
-transport <mode>Force transport: auto | ws | quic.

Reference

Commands

Every clawee <command> verb:

statusProbe the transport chain hop-by-hop: socket → daemon → relay → claweed → auth.
sessions [--watch]List the daemon's pty sessions; --watch streams live session events.
devices <list|approve|revoke>Enroll and manage device keys (approve/revoke <fp>).
relays <list|probe|priority|skip|use>Rank relays (LAN-first); bare relays opens an interactive picker.
gw [list|name …]Gateways: group local sessions by gateway; list; name a gateway.
doctor [--fix]Diagnose the local setup; --fix repairs what it can.
update [--dry] [--force]Self-update from release.clawee.org (shows the gap; skips if current).
lock-passphraseSet the idle-lock passphrase in the local config.
versionPrint the clawee version (also --version).
helpPrint the full help (also --help, -h).

Reference

Gateways

When your device is paired to more than one gateway, clawee scopes everything per gateway — sessions, relays, and the OS user. Pick one by short name, fall back to the chooser, or set friendly names.

clawee <name>Attach scoped to that gateway (matches a short name, the gateway's name, or a fingerprint prefix).
clawee gwList local sessions grouped by gateway, with live/dead state.
clawee gw listList all paired gateways with session counts.
clawee gw name <fp|name> <short>Set a friendly short name for a gateway.

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.

Reference

In-session keys

Once attached, keystrokes pass through to the remote shell except:

Ctrl+]Open the command composer (type a /command or text; Enter sends).
Ctrl+\Lock the screen (unlock with the idle-lock passphrase).
F5 · Ctrl+[Redraw the remote screen.
gIn the session picker (not while attached): open the gateway chooser.

Reference

Slash commands

Inside the composer (Ctrl+]):

/uploadSend a file to the session — /upload <path> (also: paste a path or drop a file).
/downloadFetch a remote file or dir to your machine — /download <path>.
/nameSet the session's display name — renames the remote pty.
/relaysRelay priority & skip — ↑↓ select · K/J reorder · s skip · u pin · a auto · p probe.
/settingsShow or set client upload limits — /settings [max-upload|async-upload <size>].
/historyOpen this session's full scrollback (q to quit).
/versionShow the clawee + claweed build versions.
/restartRestart the attached session in place.
/reconnectForce a reconnect now.
/detachDrop back to the session picker (the remote session keeps running).
/lockLock the screen now — /lock [<passphrase>].
/passphraseSet or clear the lock passphrase (masked entry).
/quitExit clawee.

Stuck? clawee doctor diagnoses the chain, and clawee status shows exactly where a connection stops.