Codex pets guide

Package format, install steps, validator rules, and OpenPets resource policy for Codex pet packs.

Package format

A Codex pet pack is a single folder that contains exactly the runtime files OpenPets exports:

<pet-id>/
├── pet.json
└── spritesheet.webp

The downloadable ZIP keeps that folder as its only top-level entry. OpenPets rejects ZIP paths with ../, absolute paths, or extra preview assets.

Manifest baseline

pet.json should describe the pet identity and the spritesheet contract:

{
  "id": "terminal-raccoon",
  "displayName": "Terminal Raccoon",
  "description": "A calm Codex companion for long review sessions.",
  "spritesheetPath": "spritesheet.webp",
  "version": "1.0.0",
  "frame": { "width": 192, "height": 208, "columns": 8, "rows": 9 }
}

OpenPets uses a 1536×1872 atlas, split into 8×9 frames of 192×208 pixels. The validator checks manifest shape, required animations, image type, frame bounds, and ZIP entries.

Create workflow

/create is a paid generation workbench, not a public publishing shortcut.

Choose Text to Pet or Image to Pet.
Confirm the prompt is original or authorized.
The server checks login, credits, provider state, and task cost.
A task is written to ShipAny ai_task and linked to an OpenPets generation record.
Provider results are persisted to R2 before export.
Quality FAIL blocks export. WARN and PASS may export a local draft ZIP.
No AI draft enters the public Gallery without human review.

Live KIE calls stay locked until the Worker secret, provider mode, and budget approval are all present.

Install a reviewed pack

Open a reviewed pack in /pets.
Download the .codex-pet.zip file.
Unzip it into your local Codex pets directory.
Confirm the folder still contains only pet.json and spritesheet.webp.
Select the pet from Codex settings or your local pet picker.

Resource policy

OpenPets separates resources into clear states:

State	Meaning	OpenPets behavior
reviewed seed	Local pack with manifest, spritesheet, license note, and ZIP verified	Shown in Gallery with download
draft	User or AI output that passed enough checks for local export	Visible only in the owner workflow
index-only	Public external pet page without redistribution evidence	Link out only; no mirrored ZIP or spritesheet
blocked	Unclear, unsafe, or high-IP-risk source	Not shown as a pack

External examples are useful for discovery, but OpenPets does not mirror third-party assets unless redistribution is explicitly verified.

Troubleshooting

ZIP has extra files: rebuild it so the root contains one pet folder only.
Spritesheet type is wrong: export as spritesheet.webp; PNG is treated as an intermediate source.
Animation frames fail validation: make sure each frame index is inside the 8×9 atlas.
Provider is locked: configure secrets and budget approval before live generation.
Quality status is FAIL: fix the manifest or image before export; FAIL output is not downloadable.