81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# Mosaic tmux Fleet PoC
|
|
|
|
This directory contains the first durable tmux-backed fleet primitives for the
|
|
Mosaic software-factory model.
|
|
|
|
The lifecycle model follows the organization-neutral AI Guide playbook
|
|
`mosaicstack/aiguide:playbooks/tmux-fleet.md` (commit `2a0b0b5`): a dedicated
|
|
holder owns the tmux server/socket; agent units join it and stop only their own
|
|
exact-match session.
|
|
|
|
## Layout
|
|
|
|
- `mosaic-tmux-holder.service` — user-mode holder that owns the named tmux server.
|
|
- `mosaic-agent@.service` — user-mode template for one reusable agent session.
|
|
- `mosaic-interaction-agent@.service` — generic Pi operator-interaction template
|
|
that fails fast when its pinned runtime policy is incomplete or changed.
|
|
- `test-fleet-units.sh` — validates unit syntax and required relationships.
|
|
|
|
The agent template calls:
|
|
|
|
```text
|
|
~/.config/mosaic/tools/fleet/start-agent-session.sh <agent-name>
|
|
```
|
|
|
|
which starts or reuses a tmux session on `MOSAIC_TMUX_SOCKET`.
|
|
|
|
## Generated environment and local data
|
|
|
|
The roster-derived projection is written outside the package at:
|
|
|
|
```text
|
|
~/.config/mosaic/fleet/agents/<agent>.env.generated
|
|
```
|
|
|
|
Systemd does not read either environment file. It starts the launcher with a fixed cleared bootstrap
|
|
environment; before it creates, queries, or stops an exact agent tmux session, `start-agent-session.sh`
|
|
strictly parses the generated projection and the optional local data file:
|
|
|
|
```text
|
|
~/.config/mosaic/fleet/agents/<agent>.env.local
|
|
```
|
|
|
|
The local file may contain only safe machine-specific data (`MOSAIC_RUNTIME_BIN`, heartbeat paths or
|
|
interval, and Claude configuration paths). It cannot override roster-derived keys, carry a command,
|
|
or contain secret-like/unknown keys. Both files must be private regular files. Do not hand-edit the
|
|
generated projection; update the roster and regenerate it instead. A legacy `<agent>.env` is
|
|
consumed only for regeneration, strict relocation, or private quarantine and is never launch input.
|
|
|
|
See `docs/fleet/reference/generated-env-boundary.md` for the full contract.
|
|
|
|
## Manual canary sequence
|
|
|
|
Use the roster and the supported installer; do not pre-create the agent environment directory or
|
|
edit a generated projection. `mosaic fleet install` validates the roster, installs the units and
|
|
helpers, and writes private roster-derived projections before any service is started.
|
|
|
|
```bash
|
|
# Create a site-owned canary roster. Inspect an existing roster before using --force.
|
|
mosaic fleet init --profile minimal --write
|
|
mosaic fleet install
|
|
systemctl --user daemon-reload
|
|
mosaic fleet start canary-pi
|
|
tmux -L mosaic-fleet ls
|
|
```
|
|
|
|
For an operator-interaction service, first put `<agent-name>` in the roster with the pinned Pi
|
|
runtime, model, reasoning, and `operator-interaction` tool policy. Re-run `mosaic fleet install` after
|
|
that roster change so it writes `<agent-name>.env.generated`; ambient `MOSAIC_AGENT_*` values are not
|
|
launch authority. The generic unit instance uses that generated identity, and no service source is
|
|
renamed for an instance:
|
|
|
|
```bash
|
|
mosaic fleet install
|
|
systemctl --user daemon-reload
|
|
systemctl --user start mosaic-interaction-agent@<agent-name>.service
|
|
~/.config/mosaic/tools/fleet/print-interaction-effective-policy.sh <agent-name>
|
|
```
|
|
|
|
Do not use `tmux kill-server` without `-L mosaic-fleet`; this pattern is meant
|
|
to avoid disturbing the user's default tmux server.
|