clawdie-iso/live/operator-session/clawdie-live-seed.README.txt

CLAWDIE LIVE USB — SEED PARTITION
=================================

This FAT32 partition lets you customize the live USB BEFORE flashing or
between boots. On every boot, /usr/local/etc/rc.d/clawdie_live_seed imports
an allowlisted set of files from this partition. Editing a file and
rebooting re-applies it — the importer is idempotent.

USAGE FROM LINUX / macOS / WINDOWS
----------------------------------

1. Flash the image to USB (dd, or write the .img directly).
2. Mount the CLAWDIESEED partition (typically the third partition on the
   stick, e.g. /dev/sdX3 on Linux):

       sudo mount -t vfat /dev/sdX3 /mnt/clawdie-seed

3. Drop seed files (see the two layers below).
4. Unmount and boot the USB:

       sync
       sudo umount /mnt/clawdie-seed


LAYER 1 — SIMPLE ALLOWLIST (top level)
--------------------------------------

  /authorized_keys      Public SSH keys for the operator account.
                        Installed to ~clawdie/.ssh/authorized_keys
                        (mode 0600, owner clawdie:clawdie). CRLF
                        line endings are stripped automatically.

  /ssh/authorized_keys  Same as above, in a nested ssh/ namespace.
                        Takes precedence over /authorized_keys.


LAYER 2 — PER-AGENT DIRECTORIES
-------------------------------

Create one directory per agent. THE DIRECTORY NAME IS THE AGENT NAME.
Inside it, any of these are honored:

  /<agent>/env                   Plaintext KEY=VALUE lines. Merged into the
                                 agent's .env (mode 0600). Keys you list
                                 replace existing values; keys you omit are
                                 preserved. Blank/`#` lines are ignored.
                                 Typical contents: provider API keys
                                 (ANTHROPIC_API_KEY=..., ZAI_API_KEY=...),
                                 or the Vaultwarden bootstrap
                                 (BW_CLIENTID/BW_CLIENTSECRET/BW_PASSWORD).
                                 The Vaultwarden endpoint is baked into the
                                 image; do not put it on the seed unless you
                                 are deliberately overriding it.

  /<agent>/harness.toml          Which agent harness to run + basic knobs:

                                     harness = "zot"   # zot | pi | local
                                     model = "claude-opus-4-8"
                                     cost_mode = "smart"

                                 `harness` must be one of zot, pi, local
                                 (Colibri's AgentRuntime). Recorded for the
                                 runtime to launch the right harness.

  /<agent>/soul/                 A layered-soul backup tree (SOUL.md, USER.md,
                                 IDENTITY.md, memories/, skills/, ...). Staged
                                 under /var/db/clawdie/seed/<agent>/soul for
                                 the agent workspace to load.

  /<agent>/ssh/authorized_keys   Public SSH keys for this agent.

Agent directory names may contain only A-Z a-z 0-9 . _ - (no spaces or
slashes). The name `ssh` is reserved for Layer 1.

LIVE USB vs DEPLOYED
--------------------

The live USB is single-agent: the FIRST agent directory (alphabetical) maps
to the clawdie user and becomes the active agent (recorded at
/var/db/clawdie/seed/active-agent). Additional agent directories are staged
and logged, but a second live identity is NOT provisioned here — multi-agent
provisioning is a deployed-host feature.


CONSUME-AND-SHRED (optional)
----------------------------

Drop an empty file named `shred` at the seed root to have the importer wipe
all `env` files from this partition AFTER importing them, so secrets do not
persist on the stick:

       /shred

This needs a writable seed; if the remount fails the env files are left in
place and the importer logs it. Off unless you add the marker, per stick.


SECURITY — READ THIS
--------------------

  - This is FAT32: UNENCRYPTED and readable by anyone who plugs the stick
    into any machine. There is no access control on this partition.
  - By operator decision, env files here MAY carry secrets (API keys, and
    the Vaultwarden bootstrap, which includes the master password). That is a
    deliberate trade-off: treat every seeded stick as SECRET-BEARING MEDIA.
    Do not lose it; do not lend it; prefer `shred` for one-shot provisioning.
  - Imported secrets land mode 0600 owned by the agent user. Public SSH keys
    are not secret and are always safe to place here.
  - The importer runs at every boot. Removing a file from the seed and
    rebooting does NOT remove an already-installed copy from the live system;
    re-flash the image to wipe state.

The importer logs to /var/log/clawdie-live-seed.log
(`service clawdie_live_seed status` tails it).


CONTACT
-------

clawdie.si — repository: clawdie-iso, files:
  live/operator-session/clawdie-live-seed
  live/operator-session/clawdie-live-seed.README.txt