113 lines
3.0 KiB
Markdown
113 lines
3.0 KiB
Markdown
# Local Fleet Canary
|
|
|
|
The local fleet canary runs a small tmux-backed Mosaic agent fleet on an
|
|
isolated tmux socket. The default socket is `mosaic-factory`; the commands do
|
|
not use or stop the default tmux server.
|
|
|
|
## Files
|
|
|
|
Product-owned defaults:
|
|
|
|
- `packages/mosaic/framework/fleet/roster.schema.json`
|
|
- `packages/mosaic/framework/fleet/examples/minimal.yaml`
|
|
- `packages/mosaic/framework/fleet/examples/local-canary.yaml`
|
|
- `packages/mosaic/framework/systemd/user/mosaic-tmux-holder.service`
|
|
- `packages/mosaic/framework/systemd/user/mosaic-agent@.service`
|
|
- `packages/mosaic/framework/tools/fleet/start-agent-session.sh`
|
|
- `packages/mosaic/framework/tools/tmux/agent-send.sh`
|
|
- `packages/mosaic/framework/tools/tmux/send-message.sh`
|
|
|
|
Site-owned local roster:
|
|
|
|
```text
|
|
~/.config/mosaic/fleet/roster.yaml
|
|
```
|
|
|
|
Do not put a host-specific full roster into product defaults. Start from an
|
|
example and edit the local roster after `mosaic fleet init --write`.
|
|
|
|
## Install
|
|
|
|
Minimal canary:
|
|
|
|
```bash
|
|
mosaic fleet init --profile minimal --write
|
|
# If a site-owned roster already exists, inspect it first; overwrite only explicitly:
|
|
# mosaic fleet init --profile minimal --write --force
|
|
mosaic fleet install-systemd
|
|
systemctl --user daemon-reload
|
|
mosaic fleet start
|
|
mosaic fleet verify
|
|
```
|
|
|
|
Small dogfood roster:
|
|
|
|
```bash
|
|
mosaic fleet init --profile local-canary --write
|
|
# Use --force only after preserving any site-owned roster changes.
|
|
mosaic fleet install-systemd
|
|
systemctl --user daemon-reload
|
|
mosaic fleet start
|
|
mosaic fleet status
|
|
```
|
|
|
|
## Agent Operations
|
|
|
|
```bash
|
|
mosaic agent roster
|
|
mosaic agent status
|
|
mosaic agent status canary-pi
|
|
mosaic agent send canary-pi --message "status check"
|
|
mosaic agent reset canary-pi --new
|
|
mosaic agent tail canary-pi -n 80
|
|
```
|
|
|
|
These commands read the roster and target the configured tmux socket. The
|
|
generated systemd agent services use `start-agent-session.sh`; message delivery
|
|
uses the tmux send tools with `-L mosaic-factory`.
|
|
|
|
## Verification
|
|
|
|
Use these checks before expanding the roster:
|
|
|
|
```bash
|
|
tmux -L mosaic-factory ls
|
|
tmux ls
|
|
mosaic fleet verify
|
|
systemctl --user status mosaic-tmux-holder.service
|
|
```
|
|
|
|
Expected results:
|
|
|
|
- `tmux -L mosaic-factory ls` shows `_holder` and roster agent sessions.
|
|
- `tmux ls` shows only the default tmux server sessions and is not changed by
|
|
fleet start/stop operations.
|
|
- `mosaic fleet verify` checks exact session targets on the isolated socket.
|
|
|
|
## Rollback
|
|
|
|
Stop the local canary:
|
|
|
|
```bash
|
|
mosaic fleet stop
|
|
systemctl --user disable mosaic-agent@canary-pi.service
|
|
systemctl --user disable mosaic-tmux-holder.service
|
|
systemctl --user daemon-reload
|
|
```
|
|
|
|
For a full local cleanup of generated canary files:
|
|
|
|
```bash
|
|
rm -f ~/.config/systemd/user/mosaic-agent@.service
|
|
rm -f ~/.config/systemd/user/mosaic-tmux-holder.service
|
|
rm -rf ~/.config/mosaic/fleet
|
|
rm -rf ~/.config/mosaic/tools/fleet
|
|
```
|
|
|
|
This rollback leaves the default tmux server untouched. If a canary session is
|
|
still present after service stop, remove only the isolated socket server:
|
|
|
|
```bash
|
|
tmux -L mosaic-factory kill-server
|
|
```
|