Sam & Claude
7300fec1e2
Combined from three feature branches: - feature/hw-probe-agent-bootstrap: JSON hardware probe (clawdie-hw-probe), remove desktop icon, update START-HERE.txt - chore/0.12.0-model-fix-bump: deepseek-v4-pro model names, version 0.12.0 - feature/mother-mcp-infra: build-colibri.sh MCP tool, colibri-mcp-ssh wrapper
160 lines
7.4 KiB
Text
160 lines
7.4 KiB
Text
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. Keys you list
|
|
replace existing values; keys you omit are
|
|
preserved. Blank/`#` lines are ignored.
|
|
Routing for the ACTIVE agent:
|
|
- Provider API keys and toggles
|
|
(DEEPSEEK_API_KEY=..., OPENROUTER_API_KEY=...,
|
|
COLIBRI_AUTOSPAWN_PI=YES, ...) are merged
|
|
into BOTH the agent's ~/.env AND the daemon's
|
|
/usr/local/etc/colibri/provider.env (mode
|
|
0600). Because the importer runs before the
|
|
daemon starts, a seeded provider key makes
|
|
colibri_daemon auto-spawn the agent on first
|
|
boot with NO operator action — fully
|
|
zero-touch. No Vaultwarden round-trip needed.
|
|
- Vaultwarden bootstrap creds
|
|
(BW_CLIENTID/BW_CLIENTSECRET/BW_PASSWORD) are
|
|
routed to ~/.config/vault-bootstrap.env for
|
|
clawdie-vault-fetch — use these only if you
|
|
want the vault-fetch path instead of direct
|
|
keys.
|
|
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 = "deepseek-v4-pro"
|
|
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 INBOUND: public keys allowed to SSH INTO this
|
|
node. Installed to ~/.ssh/authorized_keys (0600).
|
|
|
|
/<agent>/ssh/<name> OUTBOUND: a private client key so this node can
|
|
SSH OUT hands-free (e.g. node -> mother).
|
|
Installed to ~/.ssh/<name> (0600). The private
|
|
key rides on this offline seed instead of being
|
|
baked into the image, so the image stays
|
|
secret-free. Any file here that is not
|
|
authorized_keys/config/known_hosts and does not
|
|
end in .pub is treated as a private key.
|
|
|
|
/<agent>/ssh/<name>.pub OUTBOUND: installed to ~/.ssh/<name>.pub (0644).
|
|
|
|
/<agent>/ssh/config OUTBOUND: installed to ~/.ssh/config (0600).
|
|
Typical use — a host alias for the mother server:
|
|
|
|
Host mother
|
|
HostName osa.smilepowered.org
|
|
User clawdie
|
|
IdentityFile ~/.ssh/osa-mother-2026
|
|
|
|
/<agent>/ssh/known_hosts OUTBOUND: merged into ~/.ssh/known_hosts (0644),
|
|
de-duplicated. Pin the mother server's host key
|
|
here so the first node -> mother connection does
|
|
not stop on an unknown-host prompt. Get the line
|
|
with: ssh-keyscan osa.smilepowered.org
|
|
|
|
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
|