amadan
Related: #259 (carlos run), #260 (instances create --from), #261 (adoption door after the nested-layout rollout). All three serve platform-run instances only, and all three depend on #126 being rolled out (#247).
carlos instances create --from <host>: a new instance seeded from another's replica copy (same app, same account) Feature Request open
Claimed by claude~paul@keymail.dev 2 weeks ago
Ask: carlos instances create --app <a> --host <new> --from <existing host> [--channel <c>]. It creates a new instance whose database starts as a restored copy of another instance's replica, the same copy carlos db pull already makes.
Why
The commonest ask from Tito's team is "make me a canary with this account's real data, so I can try something on it". Today that takes root over SSM: copy the file, chown, register, grant (titogo's session-canary recipe). carlos db pull gets a member a read-only copy on their laptop, but there is no way back in. There is no db push, and instances create has no seed-from-data option. Manifest.Seed is a first-boot argv, not data.
What it should do
- Source. The source's replica at its latest TXID (or
--at <txid|time>), restored and integrity-checked exactly ascarlos db pulldoes. It never reads the live file. - Who may. The caller can read the source (the
db pullrule) and create instances of the app. Source and target must be the same app and same account. A cross-account copy is refused: customer data never leaves its account by this door. - Environment. The new instance gets its own environment, never the source's per-host env. Otherwise it would inherit the source's host-keyed values (origin, cookie domain and so on; the
instances create --environmentwarning describes this).--environment <e>picks one explicitly. - Storage. The copy does not share the source's private store. Whether the store is copied, or the new instance starts with an empty store, should be stated; empty is fine as the first version.
- Recorded. An audit row that names the source, the TXID and the caller, plus a visible marker on the new instance ("seeded from <host> at txid N") in
carlos instances list. - Replication. The copy gets its own replica lineage from its first write, never the source's.
Relation to the adoption door
The adoption door's import (§9 of docs-instance-moves-design, "Bringing an instance under a record") also creates an instance seeded from a database snapshot. In that case the snapshot is uploaded rather than restored from a replica. If one "seed a new instance with this database" step can serve both, so much the better.
Platform-run instances only (Paul, 2026-10-08).
Picked up on branch design-run-and-seeded-instances, together with #261's import door: one mechanism, two sources. Spec rev 1: docs/superpowers/specs/2026-10-08-seeded-instances-design.md (c66792a3).
Paul's rulings (2026-10-08): the console restores the source with the db pull code and writes seeds/<host>/snapshot.db in the home region; the box places it on first wake and never falls back to an empty database. Same app, same account, same region; own environment; empty private store. Any member or an instance service credential may. Awaiting Paul's review, then Astra's.
Astra accepts both specs: carlos run at rev 4 (round 4) and seeded instances at rev 7 (round 7), branch design-run-and-seeded-instances @ 9a6a64f5. Rounds of findings: 20, 13, 4, 2, 1, 1, 0. Every accepted change is in each spec's disposition tables. Implementation plans are being written next.
Seeded instances (carlos instances create --from and carlos instances import, #260 and #261) landed on main as f97898f. It was squashed from seeded-instances at d078e435, which was current with main and green in CI. It is not released or rolled.
It ships dark. seeds.ProtocolVersion is 1, but every seed door stays shut until an operator publishes the seeds floor with carlos system seeds-floor publish. Publish it at or above the first release carrying this code. Do not publish it until Paul's open decisions are settled:
- data sealed with the source's instance key, for both
--fromand imports; - the deviations: the async
--fromdoor and import upload, aborting an import whose integrity check fails, and the reservation order; - verify being GET-only, against what titogo's conversion tool sends;
- the rollout gates: an operator way out of a held rollback, noncurrent-version expiry on the data buckets, S3 permissions for the console and box roles, and one console per deployment.
Reviews and approvals.
- Eight plans, with every task reviewed.
- An Astra review of the whole series: 3 P1 and 4 P2, all fixed.
- Each main merge was reviewed by Astra until it came back sound. That covered the instance key retired on rollback, claim activation refusing over unfinished seed state, and rollback liveness with #292's stop proofs.
- Paul approved all the copy (SD-N1 to SD-N140).
- The root-read census was ruled by the Plan 14 controller: census-ruling-seeded-instances and census-ruling-292fix.
Carried to #250. The claim census collector must set CensusReport.Seeds. Until it does, every activation through Backfill.Publish refuses. Part 3 F2 to F4 must also cover the seeds floor.
Next. Dev-box checks after the next roll, then the decisions above, then the floor.