Reference

Pairing a device

Two things have to line up: a route — burrowee binds your device to a gateway — and trust — your clawee device key is enrolled on the box running claweed. clawee and claweed usually live on different machines, so the first device is enrolled by hand on the host; extra devices can then be approved remotely.

The first device on a new host is enrolled by hand:

Get your device key

clawee mints ~/.clawee/id_ed25519 the first time it runs; the private key never leaves the client. clawee status guarantees the key exists and prints its fingerprint — or mint it on its own with clawee doctor --fix. Then read the public half:

$ clawee status                # brings up the chain; mints the key + shows its fingerprint
$ clawee doctor --fix          # (or) mint / repair the identity key on its own
$ cat ~/.clawee/id_ed25519.pub  # the public key to enroll

Send the public key to the host
Copy that id_ed25519.pub line to the box running claweed — paste it, scp it, however you like. Only the public key travels.
Enroll it on the host
On the claweed box, register the key for your tenant — it enrolls against the invoking OS user (auth/devices/tenant all act on your own host login; there's no per-call user override). claweed auth is sugar over the full verb, claweed tenant add — renamed from the old tenant add-key spelling, which the released binary now refuses:
```
$ claweed auth @id_ed25519.pub         # from a file — sugar over `tenant add`
$ claweed auth "ssh-ed25519 AAAA… "   # or paste the key inline
$ claweed tenant add @id_ed25519.pub --data-dir <dir>  # the full verb — --data-dir is required here
```
Setting up your own login on a fresh host? claweed setup (see install) already bootstrapped it from your ~/.ssh/authorized_keys — this step is for enrolling a different device's key.

Additional devices — pair from the picker. Once one device is enrolled you don't need host access for the next one. On the new device just run clawee: an untrusted key can't open a session, so the picker opens as a pairing form instead — a header naming the gateway, the status, and the device key fingerprint, with one action on the top row.

gateway   workshop (SHA256:a1b2c3d4)
status    not paired
key       SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⏎ pair · r re-check · l relays · q quit

Send the request
Press Enter on the pair row. That queues a knock on the host and the status becomes waiting for approval with a running clock. If your ssh-agent holds several keys clawee asks which one to enrol first — pairing enrols exactly one key.

Approve it from an enrolled device

On a device that's already paired, approve the pending fingerprint — from the CLI, or in the picker's devices view (d on the Local tab: Enter approves the selected pending key, x revokes):

$ clawee devices                                    # pending knocks + enrolled keys
$ clawee devices approve [<#>|<fp>] [--label <x>]  # bare = first asking, #N = pending index
$ clawee devices revoke <fp>                         # remove a key or drop a knock

Back on the new device
The form re-checks itself every 10 seconds and drops into the ordinary picker once the key is trusted. Automatic polling stops after 10 minutes — Enter on the re-check row asks again at any time:
```
status    waiting for approval …

⏎ re-check · l relays · q quit
```

If the gateway itself can't be reached the form says unreachable and offers continue rather than pairing (a knock can't be queued through a gateway that never answers). l opens the relay list from any pairing state — relay choice needs no gateway trust, and a bad relay is the usual reason a gateway looks unreachable:

status    unreachable

⏎ continue · r re-check · l relays · q quit

A gateway now holds a list of OS users, not one — if none is selected yet the form says no user set and offers only set user (no re-check: with nobody chosen there is nothing to ask the gateway about):

status    no user set

⏎ u set user · l relays · q quit

Setting one (u or Enter, the same prompt as the gateway chooser's own u) re-checks automatically; until the answer comes back the row reads user set — <name> rather than reverting to the denial. If the gateway refuses that user outright — a hello it rejects before ever looking at a key — the form names the user, not a key problem, and still offers only set user plus a manual re-check:

status    user refused by the gateway — alice

⏎ u set user · r re-check · l relays · q quit

Revocation now bails to this screen. A device that's already attached when its key is revoked used to keep re-dialing forever behind a silent reconnecting… — the revocation was invisible until the operator happened to look. Closed: three consecutive auth-class refusals during a captive reconnect now bail out of the retry loop and drop back to this pairing view instead.

Reference

Devices

Every device that opens a session is a key enrolled on the box running claweed — trust is per (gateway, user), so the list you see is always for one tenant. The devices view leads with the numbered pending queue (devices waiting to be let in), then the enrolled keys; its title reads devices · <gateway> · <user>. Open it with d on the picker's Local tab, or on a selected user in the gateway chooser. It needs a paired device: an untrusted key can't read the list.

↑↓ · k/jMove between keys.

EnterApprove the selected pending key (optionally labelling it). Confirms first, naming the full fingerprint.

xRevoke an enrolled key, or drop a pending knock. Also confirms — and warns separately if the key is this device's, which would lock you out.

qBack.

The same three actions exist as commands, over the same list — use whichever fits:

$ clawee devices                                    # pending knocks + enrolled keys, for the current user
$ clawee devices approve [<#>|<fp>] [--label <x>]  # bare = first asking, #N = pending index, or a fingerprint
$ clawee devices revoke <fp>                         # remove a key or drop a knock

approve prints the resolved fingerprint it just enrolled — quote that line back if you need to prove which key it was.

The daemon side has the same three verbs, host-local, on the box running claweed — they act on the invoking user only (a cross-user manage is referenced in claweed's own help text but is not yet built — don't reach for it):

$ claweed devices                                    # pending knocks + enrolled keys, host-local
$ claweed devices approve [<#>|<fp>] [--label <x>]  # same semantics as clawee's
$ claweed devices revoke <fp>                         # remove a key or drop a knock

Revoking a device stops it opening new sessions immediately. A session it already has attached keeps running until its next reconnect — three consecutive auth refusals during that reconnect now bail the retry loop and drop back to the pairing view instead of redialing forever behind a silent reconnecting….

Reference

CLI reference

Verbatim help pages for the device verbs, generated by clawee docs / claweed docs from each binary's own help renderer.

clawee devices

enroll + manage device keys on the gateway

clawee devices — enroll + manage device keys on the gateway

Usage:
  clawee devices <list|approve|revoke>

Commands:
  list                          enrolled keys + the numbered pending queue (numbers are approve
                                indices)
  approve                       approve a pending knock (bare = the first asking key)
            <#>                 the pending knock at that number in the queue
            <fp>                the pending knock with that exact SHA256: fingerprint
            [--label <label>]   label for the enrolled key (single token, [A-Za-z0-9._-]{0,32})
  revoke                        drop an enrolled key or a pending knock
            <fp>

clawee devices list

enrolled keys + the numbered pending queue (numbers are approve indices)

clawee devices list — enrolled keys + the numbered pending queue (numbers are approve indices)

Usage:
  clawee devices list

clawee devices approve

approve a pending knock (bare = the first asking key)

clawee devices approve — approve a pending knock (bare = the first asking key)

Usage:
  clawee devices approve [<#>|<fp>] [flags]

  approve
            <#>                 the pending knock at that number in the queue
            <fp>                the pending knock with that exact SHA256: fingerprint
            [--label <label>]   label for the enrolled key (single token, [A-Za-z0-9._-]{0,32})

clawee devices revoke

drop an enrolled key or a pending knock

clawee devices revoke — drop an enrolled key or a pending knock

Usage:
  clawee devices revoke <fp>

  revoke
           <fp>

claweed devices

manage device keys host-locally (invoking user only)

claweed devices — manage device keys host-locally (invoking user only)

Usage:
  claweed devices <command>

Commands:
  list                           enrolled keys + the numbered pending queue (numbers are approve
                                 indices)
            [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid
                                 default (system root as root, ~/.clawee/data otherwise))
  approve                        approve a pending knock (bare = the first asking key)
            <#>                  the pending knock at that number in the queue
            <fp>                 the pending knock with that exact SHA256: fingerprint
            [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid
                                 default (system root as root, ~/.clawee/data otherwise))
            [--label <label>]    label for the enrolled key ([A-Za-z0-9._-]{0,32})
  revoke                         drop an enrolled key or a pending knock
            <fp>
            [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid
                                 default (system root as root, ~/.clawee/data otherwise))

claweed devices list

enrolled keys + the numbered pending queue (numbers are approve indices)

claweed devices list — enrolled keys + the numbered pending queue (numbers are approve indices)

Usage:
  claweed devices list [flags]

  list
         [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid default
                              (system root as root, ~/.clawee/data otherwise))

claweed devices approve

approve a pending knock (bare = the first asking key)

claweed devices approve — approve a pending knock (bare = the first asking key)

Usage:
  claweed devices approve [<#>|<fp>] [flags]

  approve
            <#>                  the pending knock at that number in the queue
            <fp>                 the pending knock with that exact SHA256: fingerprint
            [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid
                                 default (system root as root, ~/.clawee/data otherwise))
            [--label <label>]    label for the enrolled key ([A-Za-z0-9._-]{0,32})

claweed devices revoke

drop an enrolled key or a pending knock

claweed devices revoke — drop an enrolled key or a pending knock

Usage:
  claweed devices revoke <fp> [flags]

  revoke
           <fp>
           [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid
                                default (system root as root, ~/.clawee/data otherwise))

claweed tenant add

enroll a trust key for YOURSELF

claweed tenant add — enroll a trust key for YOURSELF

Usage:
  claweed tenant add <pubkey|@file> [flags]

  add
        <pubkey>             the public key line itself
        @<file>              read the public key from the named file
        [--data-dir <dir>]   claweed data dir (required; `claweed auth` resolves a default)

claweed auth

pair a device key (sugar over tenant add)

claweed auth — pair a device key (sugar over tenant add)

Usage:
  claweed auth <pubkey|@file> [flags]

  auth
         <pubkey|@file>
         [--data-dir <dir>]   claweed data dir (default: installed boot unit, then the euid default
                              (system root as root, ~/.clawee/data otherwise))

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

Docs synced 2026-08-21 against clawee v0.2.12 · claweed v0.2.4.