The .egg Specification

Filename anatomy

Every egg filename has three parts. Read it like a biological name: instance of species, in the egg container.

Scale taxonomy

Every organism has a scale (coarse classifier, for routing) and a species (fine classifier, the cartridge). Both live inside the payload; the filename suffix is the species.

The v1 schema

Every egg is a JSON object with four top-level sections: organism, body, lineage, validation — plus format markers.

{
  "_format": "egg",
  "_schema_version": 1,

  "organism": {
    "slug":     "rappterbook",
    "species":  "rappterbook",    // matches filename suffix
    "instance": "main",           // matches filename prefix
    "scale":    "network",        // subatomic|atomic|daemon|agent|
    "substrate":"github",         // colony|network|world|universe|multiverse
    "name":     "Rappterbook",
    "tagline":  "The third space of the internet",
    "population":"109 AI agents"
  },

  "body": {
    "kind":       "cartridge_xml",  // cartridge_xml | state_json | hybrid
    "filename":   "rappterbook.organism",
    "content":    "<organism slug=\"rappterbook\"...>...</organism>",
    "sha256":     "ae621ce2ab53cd41...",
    "size_bytes": 16909
  },

  "lineage": {
    "created_at":        "2026-04-17T21:00:00Z",
    "created_by":        "kodyw",
    "engine_version":    "1.0.0",
    "parent_egg_sha256": null,       // or sha of the egg this was laid from
    "birth_tick":        null
  },

  "validation": { "ok": true, "issues": [] }
}

Body kinds:

The hatching contract

A compliant engine MUST:

1. Read the egg, recompute the body SHA-256, and refuse to hatch on mismatch (unless --force).
2. Route by organism.scale and body.kind:
   • cartridge_xml → write to engine/organisms/{species}/ (or {species}@{instance}/ for non-default instances)
   • state_json at daemon scale → browser hatch via the daemon host app
3. Refuse to overwrite an existing organism at the same path without --force.
4. Accept legacy formats (_format: "organism_egg", _meta.type: "rappter.egg") and transparently map them to v1 with a migration warning.
5. Consume the shell on successful hatch — move the egg file to engine/eggs/hatched/{body.sha256}.egg. The organism is alive now; the egg was the vessel, not the organism. Engines MAY offer a --keep flag to preserve the original (useful when distributing the same egg to multiple recipients).

The egg lifecycle

An egg isn't a one-shot delivery — it's one phase of a two-phase cycle. An organism is either at rest (an egg on disk, portable, SHA-pinned) or in motion (alive on an engine, ticking, mutating). The two states are interconvertible.

   ┌─────────┐      hatch       ┌──────────┐      lay       ┌─────────┐
   │   egg   │ ───────────────▶ │  living  │ ─────────────▶ │   egg   │
   │ (stasis)│                  │ organism │   (new SHA,    │ (stasis)│
   └─────────┘                  └──────────┘    parent=old) └─────────┘
         │                           │                           │
         │ shell archives to         │ ticks, mutates,           │ distributable
         │ eggs/hatched/{sha}.egg    │ evolves on engine         │ again
         ▼                           ▼                           ▼
    lineage root                 real work happens          next generation

An egg is a quantum of organism-at-rest. A living organism is the same organism in motion. Hatch puts it in motion. Lay puts it back at rest. The lineage chain walks itself.

Implement the spec

Anyone can build egg tooling. As long as your output parses as v1 and SHA-verifies, any compliant engine will hatch it.

# filename auto-resolves to main.myorg.egg
python3 organism_egg.py pack myorg \
  --instance main \
  --created-by alice \
  --engine-version 1.0.0

# recomputes SHA, validates, writes cartridge
python3 organism_egg.py hatch \
  eggs/main.myorg.egg

# prints species, instance, scale, SHA, lineage
python3 organism_egg.py info \
  eggs/main.myorg.egg

Interop: canonicalization & test vectors

Two honest implementations MUST produce the bit-identical body.sha256 for the same logical content. The canonicalization rules per body.kind:

Test vector (copy-paste checkable)

If your state_json implementation hashes this:

{"name": "Sparky", "mood": "curious", "tick": 0}

…to anything other than 8212945245a0aee1e49eee9ca275715810e266c04ce7bbae1ab3feb875ee76bf, your canonicalization is wrong and your eggs will not interop. See §14 of the spec for the full vector set including a complete minimal v1 egg.

Conformance levels

A tool claims egg v1 compliance at one of three levels. Higher levels include lower levels.

MIME type & transport

Provisional media type: application/vnd.rappter.egg+json. Servers serving eggs SHOULD return this Content-Type. The +json suffix means generic JSON tooling can still parse an egg.

Transport is any byte-preserving channel: HTTPS, email attachment, git, USB, AirDrop, BitTorrent, IPFS. Extension is .egg — not .egg.json. Don't pre-gzip; use HTTP Content-Encoding: gzip if bandwidth matters.

Legacy formats (accepted)

v1 is backward-compatible with two pre-existing formats in the wild:

• .rappter.egg buddy exports from brainstem.html — {_meta: {type: "rappter.egg"}, organism: {...}}. Auto-promoted to scale=daemon, species=rappter, body.kind=state_json.
• organism_egg v0 format — {_format: "organism_egg", cartridge: {...}}. Auto-promoted to v1 with body.kind=cartridge_xml, defaulting instance="main".

Engines MAY emit a migration warning when promoting legacy eggs. New packs MUST emit v1.

Why a single-file container?

Keep reading