Codex Pets

Community gallery for Codex-compatible animated pets with local accounts, manual moderation, public generation requests, YDB-backed asset storage, and public detail pages for approved and pending pets.

Public site: https://pets.ydb-qdrant.tech/.

Stack

• Next.js 16 App Router, React 19, TypeScript strict
• Gravity UI + SCSS/BEM
• local-ydb / YDB native gRPC via ydb-sdk
• App-owned email+password auth with YDB-backed users and sessions
• Pet assets stored in YDB as binary blobs
• Dynamic robots.txt, sitemap.xml, llms.txt, llms-full.txt, and OpenAPI JSON
• Agent-facing HTTP access through llms.txt / llm.txt, /llms-full.txt, /mcp, JSON routes, and TOON mirrors for core registry data
• Optional read-only browser WebMCP tools in supported browser runtimes
• Yandex Metrika using the same counter as ydb-qdrant-ui (104844437), with optional server-side aggregate MCP metrics
• JSZip + Sharp for package validation

Development

nvm use 24
npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000.

Agent access

Codex Pets exposes a public read-only MCP server so coding agents can search, inspect, install, and share approved pet packs.

Primary public surfaces:

• Best guide: https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents
• LLM discovery: https://pets.ydb-qdrant.tech/llms.txt
• MCP endpoint: https://pets.ydb-qdrant.tech/mcp
• Public manifest: https://pets.ydb-qdrant.tech/api/manifest
• CLI install: npx @astandrik/codex-pets install <slug>

Connect Codex:

codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp

Run a local stdio MCP server that proxies the public gallery:

npx @astandrik/codex-pets mcp

Available MCP tools:

• search_pets — discover approved pets when you need candidates or lack an exact slug
• get_pet — fetch one public pet card when you already have an approved slug
• get_install_instructions — get install commands without incrementing metrics
• get_badge_code — generate README badge snippets for a known slug
• get_embed_code — generate iframe embed snippets for a known slug
• get_card_code — generate animated GIF snippets for a known slug, defaulting to sprite-only mode
• get_pet_request_info — discover the public new-pet request workflow; it does not submit or inspect private requests

HTTP fallback routes are public too:

• /openapi.json
• /api/openapi.json
• /llms-full.txt
• /guides/best-codex-pets-for-ai-coding-agents
• /guides/best-codex-pets-for-ai-coding-agents.md
• /api/manifest
• /api/manifest.toon
• /api/pets
• /api/pets.toon
• /api/pets/<slug>
• /api/pets/<slug>.toon
• /pets/<slug>/markdown
• /api/tags
• /api/tags.toon
• /api/pets/<slug>/share
• /badge/<slug>.svg
• /card/<slug>.gif
• /embed/<slug>

If you deploy under a subpath such as /codex-pets, set:

NEXT_PUBLIC_BASE_PATH=/codex-pets
NEXT_PUBLIC_APP_URL=https://example.com/codex-pets

The public gallery renders without secrets. For account login, submit, moderation, and metrics you need YDB_PETS_ENDPOINT, YDB_PETS_DATABASE, and auth env. Optional server-side MCP metrics also need YANDEX_METRIKA_MP_TOKEN and YANDEX_METRIKA_MP_CLIENT_ID. Optional IndexNow notifications are enabled by INDEXNOW_KEY; the app serves /<key>.txt and pings IndexNow after an admin approves a pet.

To run without YDB on generated sample data:

CODEX_PETS_DATA_SOURCE=mock AUTH_MODE=single-user \
  AUTH_SINGLE_USER_EMAIL=local-admin@example.com \
  NEXT_PUBLIC_APP_URL=http://localhost:3000 \
  npm run dev -- --port 3000

Production notes

For a dedicated public subdomain such as https://pets.example.com, prefer:

NEXT_PUBLIC_APP_URL=https://pets.example.com
NEXT_PUBLIC_BASE_PATH=

If the app container talks to YDB by Docker hostname, for example grpc://ydb-local:2136, run the app on the same Docker network as the YDB containers:

docker run --network ydb-net ...

Telegram and similar preview crawlers are handled by lightweight preview routes:

• /api/preview/site
• /api/preview/pets/[slug]

The reverse proxy should rewrite preview-bot requests for / and /pets/<slug> to those endpoints before proxying to the normal App Router pages. See:

• deploy/nginx-pets-subdomain.conf.example
• deploy/nginx-pets-edge-proxy.conf.example

Local YDB quickstart

For local app development, a plain local-ydb root database at /local is enough; you do not need a CMS tenant or dynamic node. The app runs on the host, so the local-ydb container must publish gRPC on 127.0.0.1:2136.

If you use the local-ydb MCP, start from a clean root database with local_ydb_destroy_stack(confirm=true) and local_ydb_bootstrap_root_database(confirm=true). If the resulting container does not publish 127.0.0.1:2136, recreate only the container on the same volume with a host gRPC port:

docker rm -f ydb-local
docker run -d --name ydb-local --no-healthcheck --network ydb-net \
  --restart unless-stopped \
  -p 127.0.0.1:2136:2136 \
  -p 127.0.0.1:8765:8765 \
  -v ydb-local-data:/ydb_data \
  -e GRPC_PORT=2136 \
  -e MON_PORT=8765 \
  -e GRPC_TLS_PORT= \
  -e YDB_GRPC_ENABLE_TLS=0 \
  -e YDB_ANONYMOUS_CREDENTIALS=1 \
  -e YDB_LOCAL_SURVIVE_RESTART=1 \
  ghcr.io/ydb-platform/local-ydb:26.1.1.6

Use these local app env vars:

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
AUTH_SINGLE_USER_EMAIL=local-admin@example.com
AUTH_SINGLE_USER_NAME="Local Admin"
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
INITIAL_ADMIN_EMAILS=local-admin@example.com

YDB_ANONYMOUS_CREDENTIALS=1
YDB_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_DATABASE=/local
NEXT_PUBLIC_APP_URL=http://localhost:3000

YDB_ENDPOINT is needed for local host-to-Docker runs because ydb-sdk otherwise follows discovery endpoints that may contain the Docker container hostname.

Apply schema, seed data, and start the app:

docker cp ydb/schema.yql ydb-local:/tmp/codex-pets-schema.yql
docker exec ydb-local /ydb -e grpc://localhost:2136 -d /local scripting yql -f /tmp/codex-pets-schema.yql
npm run db:migrate
npm run seed:dev:reset
npm run dev -- --port 3000

Open http://localhost:3000. The local YDB monitoring UI is http://127.0.0.1:8765.

For a remote or tenant-backed deployment, point the app at a reachable tenant endpoint, for example:

YDB_PETS_ENDPOINT=grpc://ydb-host:2137
YDB_PETS_DATABASE=/local/your-tenant
YDB_STATIC_CREDENTIALS_USER=appuser
YDB_STATIC_CREDENTIALS_PASSWORD_FILE=/run/secrets/app.password
YDB_STATIC_CREDENTIALS_AUTH_ENDPOINT=grpc://ydb-host:2136

For local development without a full account flow:

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
INITIAL_ADMIN_EMAILS=local-admin@example.com

For the normal built-in account flow:

AUTH_MODE=app-session
SESSION_COOKIE_SECRET=change-me
PASSWORD_PEPPER=change-me-too
INITIAL_ADMIN_EMAILS=admin@example.com

Create tables manually on the existing local-ydb tenant:

ydb -e "$YDB_PETS_ENDPOINT" -d "$YDB_PETS_DATABASE" scripting yql -f ydb/schema.yql

Apply migrations to an existing database:

npm run db:migrate

Seed local development data after the schema exists:

npm run seed:dev

Use npm run seed:dev:reset to replace only the fixed dev_* seed records.

Current behavior

• Public users can browse the gallery and open /pets/[slug].
• Public users can submit a pet without logging in by providing files and an optional contact email.
• Public users can request a generated pet without logging in by providing a contact email, text brief, and optional reference image.
• Logged-in users can see only their own pets under /my-pets.
• Logged-in users can see their own pet generation requests under /my-requests.
• Admins are determined by INITIAL_ADMIN_EMAILS.
• Admins can approve, reject, and delete pending pets from /admin/submissions.
• Admins can review generation requests and link them to existing pets from /admin/requests.
• Owners can delete their own pets from /my-pets.
• Admins can delete any pet from the pet detail page.
• Deleted pets disappear from owner lists, public listings, and sitemap.xml.

SEO, agents, and analytics

• robots.txt is served from src/app/robots.ts.
• sitemap.xml is dynamic and includes all currently approved pets.
• llms.txt is dynamic and provides a curated AI-readable map of the gallery, manifest, and approved pet pages. /llm.txt is a direct plain-text alias for fetchers that request the singular filename.
• llms-full.txt is dynamic and provides expanded AI-readable docs with API reference links, auth notes, examples, and webhooks status.
• /openapi.json is the canonical OpenAPI 3.1 specification for the public agent/developer contract subset. It intentionally omits public metric mutation and download redirect routes. /api/openapi.json is an alias for scanners that probe predictable API paths.
• /developers and /docs/api are indexed developer-resource pages for API, OpenAPI, MCP, auth, and webhooks discoverability.
• /mcp is a public read-only Streamable HTTP MCP server for coding agents. Codex can connect with: codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp.
• Official MCP Registry name: tech.ydb-qdrant.pets/codex-pets-ydb-qdrant.
• server.json and /.well-known/mcp/server.json expose MCP Registry metadata for the public remote server.
• /.well-known/mcp-registry-auth exposes the public HTTP domain auth record used by mcp-publisher.
• HTTP agent access is the primary public machine contract:
  • /mcp — Streamable HTTP MCP endpoint with read-only tools: search_pets, get_pet, get_install_instructions, get_badge_code, get_embed_code, get_card_code, and get_pet_request_info
  • /openapi.json and /api/openapi.json — OpenAPI 3.1 public agent/developer contract subset
  • /llms-full.txt — expanded LLM-readable API, auth, MCP, package, and webhooks documentation
  • /developers and /docs/api — developer portal and API docs pages
  • /server.json and /.well-known/mcp/server.json — MCP Registry metadata pointing to the public Streamable HTTP remote
  • /.well-known/mcp-registry-auth — public MCP Registry HTTP auth record
  • /api/manifest — approved pet list with page URLs, install commands, and asset URLs
  • /api/manifest.toon — TOON mirror of the public manifest for LLM-friendly retrieval
  • /api/pets?q=<query>&kind=all|creature|object|character — approved pet list/search JSON without private contact emails
  • /api/pets.toon?q=<query>&kind=all|creature|object|character — TOON mirror of approved pet list/search without private contact emails
  • /api/pets/<slug> — public detail JSON for one approved pet without private contact emails
  • /api/pets/<slug>.toon — TOON mirror of public detail data without private contact emails
  • /api/tags — current tag counts for approved pets
  • /api/tags.toon — TOON mirror of current tag counts
  • /api/pets/<slug>/share — sanitized install, badge, and embed snippets
  • /api/pets/<slug>/install — read-only install instructions with no metric mutation
  • /badge/<slug>.svg — README badge SVG
  • /card/<slug>.gif — animated GIF share surface. Supports mode=sprite|card, state, and scale; default sharable output is sprite-only.
  • /embed/<slug> — iframe embed page. Supports mode=sprite|card, state, scale, theme, compact, and visibility toggles.
  • npx @astandrik/codex-pets install <slug> — CLI install command format
• Browser WebMCP is a read-only progressive enhancement. It only works in browser runtimes that expose navigator.modelContext; ordinary HTTP crawlers and ChatGPT browsing sessions should use the endpoints above. Supported browser WebMCP tools:
  • search_codex_pets — search approved pets through /api/pets
  • get_codex_pet — fetch one approved pet through /api/pets/[slug]
  • get_codex_pets_manifest — fetch /api/manifest
  • get_current_codex_pet — inspect the approved pet open in the current tab
• WebMCP intentionally does not expose submit, like, download/install counters, auth, admin, moderation, or delete actions.
• The sitemap updates automatically after moderation changes; no cron or manual rebuild is needed for new approved pets to appear there.
• Yandex Metrika is loaded in production only and tracks:
  • account register/login success and error
  • pet submit success and error
  • pet generation request success and error
  • moderation approve/reject/delete
• Server-side MCP aggregate metrics are optional. They are enabled only when YANDEX_METRIKA_MP_TOKEN and YANDEX_METRIKA_MP_CLIENT_ID are configured. MCP metrics use a dedicated technical Metrika ClientID and send a synthetic /mcp pageview before the mcp_tool_call goal event. The payload includes only aggregate tool dimensions such as tool name, status, safe slug, kind, result count, and limit; it does not include raw MCP search text, IP address, user-agent, origin header, contact email, owner email, or owner identifiers.
• IndexNow is optional. Set INDEXNOW_KEY in the runtime env to enable the public key file and approval-time notifications for the gallery, the new pet detail page, sitemap.xml, llms.txt, and /api/manifest.

Main routes

• / — public gallery
• /request — public pet generation request flow
• /submit — public submit flow
• /login, /register, /logout — local account flow
• /my-pets — owner view
• /my-requests — logged-in user generation request view
• /admin/submissions — admin moderation queue
• /admin/requests — admin pet generation request queue
• /pets/[slug] — pet detail page
• /agents — agent and MCP connection guide
• /developers — Codex Pets Developer Portal
• /docs/api — Codex Pets API docs
• /guides/best-codex-pets-for-ai-coding-agents — category guide for Codex pet selection
• /guides/codex-pets-vs-vscode-pets — comparison guide for editor pet use cases
• /mcp — public read-only Streamable HTTP MCP endpoint
• /openapi.json, /api/openapi.json — public OpenAPI specification
• /server.json, /.well-known/mcp/server.json — MCP Registry metadata
• /api/manifest — public agent/CLI manifest
• /api/manifest.toon — TOON mirror of the public manifest
• /api/pets — public approved pet list/search JSON
• /api/pets.toon — TOON mirror of approved pet list/search
• /api/pets/[slug] — public approved pet detail JSON
• /api/pets/[slug].toon — TOON mirror of public pet detail data
• /api/tags, /api/pets/[slug]/share, /api/pets/[slug]/install — read-only agent/share JSON
• /api/tags.toon — TOON mirror of approved tag counts
• /badge/[slug].svg, /card/[slug].gif, /embed/[slug] — share surfaces
• /robots.txt, /sitemap.xml, /llms.txt, /llm.txt, /llms-full.txt — SEO and AI-readable outputs

Agent-facing checks

Use CODEX_PETS_DATA_SOURCE=mock npm run dev -- --port 3000 to smoke-check agent-facing routes without local YDB. Expected public endpoints:

curl -I http://localhost:3000/
curl -I http://localhost:3000/api/pets
curl -I http://localhost:3000/api/pets.toon
curl -I http://localhost:3000/api/manifest
curl -I http://localhost:3000/api/manifest.toon
curl -I http://localhost:3000/openapi.json
curl -I http://localhost:3000/api/openapi.json
curl -I http://localhost:3000/api/tags
curl -I http://localhost:3000/api/tags.toon
curl -I http://localhost:3000/llms.txt
curl -I http://localhost:3000/llm.txt
curl -I http://localhost:3000/llms-full.txt
curl -I http://localhost:3000/developers
curl -I http://localhost:3000/docs/api
curl -I http://localhost:3000/guides/best-codex-pets-for-ai-coding-agents
curl -I http://localhost:3000/guides/codex-pets-vs-vscode-pets
curl -i http://localhost:3000/mcp

For a JSON-response MCP smoke test:

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For WebMCP itself, use a WebMCP-capable Chrome or lab browser and check that navigator.modelContext exposes the read-only tools listed above. In normal browsers without WebMCP, the client registrar is a no-op; this is expected and does not affect the HTTP agent contract.

Private deployment notes

Concrete per-host instructions, local paths, and operational notes should live under a gitignored private/ directory. The public docs in this repo should stay generic and safe to commit.

Pet Package

Each pet is distributed as:

• pet.json
• spritesheet.webp or spritesheet.png
• downloadable ZIP containing both files at the root

The v1 validator expects an 8x9 atlas at 1536x1872, where each cell is 192x208.

CLI install

Approved gallery pets can be installed into Codex from npm:

npx @astandrik/codex-pets install zero-two-2

The CLI reads /api/manifest from https://pets.ydb-qdrant.tech by default and writes to ${CODEX_HOME:-~/.codex}/pets/<slug>/. Use --force to replace an existing local pet folder, or CODEX_PETS_URL / --url to point at another deployment. If Codex is already running, restart it before selecting the new pet in Settings -> Appearance -> Pets.