Setup

Setting up the daemon

claweed is the session broker — it runs on every box that hosts sessions. Install it, then run claweed setup once: a single first-run pass that repairs the local install and bootstraps your own login as the box's first trusted tenant.

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

$ claweed setup            # first run: doctor --fix, then bootstrap YOUR tenant keys from ~/.ssh/authorized_keys (consent-gated, idempotent)

Under the hood that's two steps run back to back: doctor --fix repairs whatever it can about the local install, then claweed reads the invoking user's own ~/.ssh/authorized_keys and offers to enroll each key it finds as that user's first trusted device. Nothing is written without consent, and running it again is a no-op once the tenant already exists.

Enrolling a different device's key — not this host's own login — is a separate step: see Devices & pairing.

Health checks

Doctor & status

Both sides speak the same two verbs. On the host, claweed doctor [--fix] [--yes] diagnoses the deployment and repairs service-user-owned bits (--yes skips consent prompts); claweed status is its read-only alias — same report, no --fix.

On the client, clawee doctor [--fix] [--yes] diagnoses the local setup and always prints the clawee + claweed versions — even when nothing connects; clawee status probes the chain hop-by-hop (socket → daemon → relay → claweed → auth) and shows exactly where a connection stops.

claweed doctor, run on the session host, reports the installed daemon version alongside the version actually running — if they differ, restart the service.

Maintenance

Update

Both components self-update in place from the signed release channel:

$ clawee update             # shows the version gap; skips if current
$ clawee update --auto      # install the update, unattended
$ clawee update --dry       # report only
$ clawee update --force     # reinstall the latest regardless
$ claweed update            # same, for the daemon
$ claweed update --auto     # apply unattended; restarts the service only if changed
$ claweed setup             # first run: doctor --fix, then bootstrap YOUR tenant keys (see Setup)

upgrade.sh is not how you upgrade — install.sh is. It's a forcing entry point for same-semver re-cuts the normal update ladder gate can't see (the version number didn't change, so update sees nothing to do):

$ curl -fsSL https://release.clawee.org/claweed/upgrade.sh | sh -s -- <version>

Operations

Service unit

The daemon installs itself as a managed boot unit — a launchd .plist on macOS, a systemd .service on Linux. claweed service print renders that unit to stdout, given the same paths and run-as identity the installer already resolved — useful for inspecting what got installed, or for a manual install on a box the installer can't reach directly.

Operations

Tenant management

claweed tenant manages your own tenant enrollment — the same enrollment claweed setup bootstraps automatically from ~/.ssh/authorized_keys on first run, and the same one claweed auth / claweed tenant add sugar over for a second device (see Devices & pairing).

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

Troubleshooting

Quick diagnostic rows, condensed from doctor/status on both sides:

clawee doctor [--fix] [--yes]Diagnoses the local setup and repairs what it can, and always prints the clawee + claweed versions — even when nothing connects.

claweed doctorRun on the session host — reports the installed daemon version alongside the version actually running; if they differ, restart the service.

clawee status / claweed statusRead-only aliases of doctor — same report, no --fix.

clawee statusProbes the chain hop-by-hop (socket → daemon → relay → claweed → auth) and shows exactly where a connection stops.

claweed setupBootstraps a first-time host: doctor --fix plus consent-gated tenant enrollment from the invoking user's own ~/.ssh/authorized_keys.

Reference

CLI reference

Verbatim help pages for the daemon-operations verbs, generated by claweed docs from the binary's own help renderer.

claweed setup

first-time setup for the invoking user — doctor --fix, then bootstrap YOUR tenant keys

claweed setup — first-time setup for the invoking user — doctor --fix, then bootstrap YOUR tenant keys

Usage:
  claweed setup

claweed doctor

diagnose the deployment; --fix repairs service-user-owned bits

claweed doctor — diagnose the deployment; --fix repairs service-user-owned bits

Usage:
  claweed doctor [flags]

  doctor
           [--allowlist <path>]              spawn-allow uid list path
           [--data-dir <dir>]                data dir (default: installed boot unit)
           [--fix]                           repair failed checks (asks consent)
           [--register-socket <path>]        gateway register socket path (default: installed boot
                                             unit)
           [--service-home <dir>]            service home dir (see --service-uid)
           [--service-uid <uid>]             service uid (default: the --data-dir owner; set by a
                                             root re-read)
           [--service-user <user>]           service user (see --service-uid)
           [--sessions-verdict <verdict>]    relayed sessions verdict (root re-read; display only)
           [--socket <path>]                 dev unix socket path (default: installed boot unit)
           [--system-uid-allowlist <path>]   system-uid opt-in path
           [--yes]                           skip consent prompts (unattended --fix)

claweed status

alias of doctor (read-only) — same report, no --fix

claweed status — alias of doctor (read-only) — same report, no --fix

Usage:
  claweed status [flags]

  status
           [--data-dir <dir>]           service data dir (default: installed boot unit, then the
                                        euid default (system root as root, ~/.clawee/data
                                        otherwise))
           [--register-socket <path>]   gateway register socket path (default: installed boot unit)
           [--socket <path>]            dev unix socket path (default: installed boot unit)

claweed update

update claweed from release.clawee.org

claweed update — update claweed from release.clawee.org

Usage:
  claweed update [flags]

  update
           [--auto]    apply unattended; restart only if changed
           [--dry]     print the update plan only, then exit
           [--force]   reinstall everything (binary + spawn policy + boot-unit) + restart

claweed service print

render the boot unit — a launchd .plist / systemd .service — to stdout

claweed service print — render the boot unit — a launchd .plist / systemd .service — to stdout

Usage:
  claweed service print [flags]

  print
          [--claweed <path>]           claweed binary path (required)
          [--group <group>]            run-as group (optional)
          [--home <dir>]               service user's home dir — the unit's HOME (always required)
          [--kind <kind>]              unit kind: launchd | systemd (required)
          [--log <path>]               launchd stderr/stdout log path (optional)
          [--register-socket <path>]   claweed --register-socket path (production)
          [--root-scheme]              root daemon, no run-as user (excludes --user/--group; --home
                                       still required)
          [--socket <path>]            claweed --socket path (dev)
          [--user <user>]              run-as user (required unless --root-scheme)

claweed tenant

manage YOUR OWN tenant enrollment

claweed tenant — manage YOUR OWN tenant enrollment

Usage:
  claweed tenant <command>

Commands:
  add                        enroll a trust key for YOURSELF
        <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)

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.