62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# Fleet Unattended First Start
|
|
|
|
> **Status:** Current for roster-owned local fleet launches after issue #1264 lands. Runtime
|
|
> installation and provider authentication remain separate prerequisites.
|
|
|
|
A fleet seat started by systemd has no operator at its pane. On its first launch, Mosaic must not
|
|
stop at the interactive identity wizard.
|
|
|
|
## What happens on first start
|
|
|
|
When `MOSAIC_AGENT_NAME` names an exact member of the installed fleet roster and top-level identity
|
|
contracts are absent, the launcher:
|
|
|
|
1. validates the exact roster member, its canonical class, and the installed fleet communications
|
|
helper;
|
|
2. reads the shipped generic contracts from
|
|
`~/.config/mosaic/defaults/SOUL.md` and `defaults/USER.md`;
|
|
3. creates only the missing top-level `SOUL.md` and `USER.md` as owner-private files;
|
|
4. preserves any existing top-level identity file byte-for-byte; and
|
|
5. launches the runtime with the roster member's exact agent/session name and role/class in composed
|
|
context.
|
|
|
|
The generic defaults do **not** make every seat the same identity. They provide a shared behavioral
|
|
base. The canonical roster row supplies each seat's exact name, class, peers, socket, and authority.
|
|
|
|
## Operator behavior
|
|
|
|
A normal standalone launch without a fleet identity retains its portable configuration path and still
|
|
uses the interactive wizard when `SOUL.md` is absent:
|
|
|
|
```bash
|
|
mosaic pi
|
|
```
|
|
|
|
A roster-owned seat may be started without attaching to its pane:
|
|
|
|
```bash
|
|
mosaic fleet start <exact-roster-name>
|
|
```
|
|
|
|
Mosaic refuses before runtime execution if the requested member is absent, its explicitly supplied
|
|
ambient class is blank or conflicts with the roster, a required default is missing or unsafe, or an existing identity contract
|
|
is not a safe regular file. Repair the named component and retry the same exact roster member; do not
|
|
copy another seat's personalized identity.
|
|
|
|
## Separate prerequisites
|
|
|
|
This behavior clears the Mosaic identity-wizard wall only. A clean host still needs:
|
|
|
|
- the declared runtime installed on the pane PATH;
|
|
- the fleet transport and generated unit assets; and
|
|
- runtime/provider authentication appropriate to that seat.
|
|
|
|
Those checks are separate so a successful identity bootstrap is not reported as a fully authenticated
|
|
agent session.
|
|
|
|
## Related
|
|
|
|
- [Administrator runbook](../../ADMIN-GUIDE/operations/fleet-unattended-first-start.md)
|
|
- [Developer architecture](../../DEVELOPER-GUIDE/architecture/fleet-first-start-identity.md)
|
|
- [Verification report](../../reports/qa/2026-08-16-1264-unattended-first-start.md)
|