jason.woltjeandjarvis
a80bae950d
ci/woodpecker/push/publish Pipeline failed
Co-authored-by: Jason Woltje <[email protected]>
81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# Mosaic Fleet Rosters
|
|
|
|
The local fleet canary uses a product-owned roster schema with site-owned roster
|
|
files. Product examples live here; active local rosters should live outside the
|
|
package, normally at:
|
|
|
|
```text
|
|
~/.config/mosaic/fleet/roster.yaml
|
|
```
|
|
|
|
The default tmux socket is `mosaic-fleet` so fleet commands do not touch the
|
|
default tmux server. The roster is the desired-state authority; generated environment files are
|
|
rebuildable projections, never a second source of configuration.
|
|
|
|
## Brain-home split (fleet state vs framework templates)
|
|
|
|
When a mosaic-brain clone is present, fleet **state** resolves from the brain
|
|
home while framework templates and dispatch state stay in the config home
|
|
(three-tree model, canon `docs/STRUCTURE-CANON.md` §2):
|
|
|
|
| Path | Without brain (legacy) | With brain |
|
|
| ------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------ |
|
|
| `fleet/agents/<seat>.env.*` | `~/.config/mosaic/fleet/agents/` | `~/.mosaic/fleet/agents/` |
|
|
| `fleet/roles.local/` (overrides) | `~/.config/mosaic/fleet/roles.local/` | `~/.mosaic/fleet/roles.local/` |
|
|
| `fleet/profiles/` (working copies) | `~/.config/mosaic/fleet/profiles/` | `~/.mosaic/fleet/profiles/` |
|
|
| `fleet/roster.yaml`, `fleet/roles/` (baseline), `fleet/run/`, `fleet/services/` | `~/.config/mosaic/fleet/…` | unchanged (config home) |
|
|
|
|
Activation (`packages/mosaic/src/fleet/brain-home.ts`, mirrored in
|
|
`tools/fleet/start-agent-session.sh`):
|
|
|
|
1. `MOSAIC_BRAIN_HOME` env var — explicit, always wins.
|
|
2. Canonical `~/.mosaic` — adopted only when `MOSAIC_HOME` is the default
|
|
`~/.config/mosaic` AND `~/.mosaic/fleet/agents` exists. Custom
|
|
`--mosaic-home` values (tests, sandboxes, canaries) never adopt, keeping
|
|
them hermetic.
|
|
3. Otherwise the config home (legacy single-tree behavior).
|
|
|
|
Seat env dirs under a brain are subject to the same privacy boundary (0700
|
|
dirs, 0600 files); `.env.generated` files are structure-valuable and tracked
|
|
in the brain repo, hand-maintained `.env`/`.env.local` stay ignored and private.
|
|
|
|
## Examples
|
|
|
|
- `examples/minimal.yaml` starts one local canary slot.
|
|
- `examples/local-canary.yaml` starts a small generic dogfood fleet.
|
|
- `examples/operator-interaction.yaml` is an example Pi operator-interaction
|
|
service; replace its example agent name before provisioning.
|
|
|
|
## Operator interaction service
|
|
|
|
`services/operator-interaction.yaml` pins the Pi runtime, GPT-5.6 Sol model,
|
|
high reasoning, and the `operator-interaction` tool policy. The agent identity
|
|
is provisioning data: choose a roster name, generate its per-agent environment
|
|
file, then start the matching generic systemd instance. The service fails before
|
|
launch if the configured identity does not match the instance or any pinned
|
|
policy field drifts.
|
|
|
|
The installed `tools/fleet/print-interaction-effective-policy.sh` prints only
|
|
the resolved name, runtime, model, reasoning, and tool policy. It never reads
|
|
or prints credential variables.
|
|
|
|
## Generated agent environment boundary
|
|
|
|
`mosaic fleet install` writes a private deterministic projection at
|
|
`~/.config/mosaic/fleet/agents/<agent>.env.generated`. It may relocate only approved local machine
|
|
data to `<agent>.env.local`; generated keys, arbitrary commands, secret-like keys, duplicate keys,
|
|
unknown keys, and unsafe permissions fail before a tmux session is created. Legacy `.env` input is
|
|
regenerated, relocated, or quarantined and is not a launch authority.
|
|
|
|
See [`docs/fleet/reference/generated-env-boundary.md`](../../../../docs/fleet/reference/generated-env-boundary.md)
|
|
for allowed local keys and the USC downstream interface evidence.
|
|
|
|
Initialize a roster:
|
|
|
|
```bash
|
|
mosaic fleet init --profile minimal --write
|
|
mosaic fleet install-systemd
|
|
mosaic fleet start
|
|
mosaic fleet verify
|
|
```
|