Pet Forge is a peer-to-peer marketplace for AI pet-agents — custom workers with a name, a role, a personality and a body. Talk to one. Hand it a task. Watch a Swarms-powered swarm of specialist agents fan out, do the work in parallel, and ship a receipt that confesses every guess they made.
Website: trypetforge.com · X: @tryPetForge
CA: FuHPtxKWCBYZzhrkGAemb3nuy6zMAnokeX2ktjTTpump
A pet. A swarm. A receipt. Every task runs through three loops you can audit — what got remembered, what got dispatched, what got guessed.
| 🐾 | 🛠 | 💸 |
|---|---|---|
| Custom pet-agents with name, role, personality, system prompt, model & avatar | Generator: stitch heads/bodies/legs from 170+ community sprites into brand-new composites | Solana mainnet marketplace — list for SOL, buyer pays your Phantom wallet directly |
| Talk to any pet, run tasks against the swarm, monitor the run live | Auto-seeded sprite catalog (170+ pets, idempotent, cached on a persistent volume) | Zero platform fees — the runtime never touches the SOL, just verifies the on-chain transfer |
| Lies Ledger on every output — agents confess assumptions, gaps, low-confidence claims | The Lair — persistent SQLite that remembers every file, link, screenshot, lesson | My Purchases filter — connect your wallet, your owned skins surface immediately |
| URL | Purpose |
|---|---|
/ |
Landing page — hero, mechanism, agent crew, marketplace pitch, lair/ledger lore, roadmap, FAQ |
/pet/ |
Run console — mascot stage, prompt/drop composer, live agent monitor, output card + Lies Ledger drawer |
/agents/ |
Agent management dashboard — built-in roster, deployed custom Pet Agents, Test-Run flow, sticky inspector |
/pets/ |
Pet skin library — paginated grid, source filters (Imported / Starter / User-made / My Purchases), assignments, list-for-sale modal |
/marketplace/ |
Community catalog — browse every pet, filter by source/compat, buy via Phantom with on-chain confirmation |
/generator/ |
Composite skin builder — pick a head + body + legs, name it, optionally list it for SOL in one screen |
graph TB
subgraph Browser
UI[Vanilla JS frontend<br/>no build step]
end
subgraph Edge["Static edge"]
Static[Static HTML/CSS/JS]
Rewrites[Path rewrites:<br/>/api/* /events /setup ...]
end
subgraph Runtime["Python runtime"]
API[REST API]
WS[WebSocket /events]
Workflow[Workflow runner<br/>Solo · Sequential · Concurrent<br/>Hierarchical · Voting]
end
subgraph External["External services"]
Lair[(SQLite lair<br/>persistent volume)]
LLM[LLM inference]
Solana[Solana mainnet RPC]
SpriteCatalog[Community sprite catalog]
end
UI -->|same-origin| Static
UI -->|/api/*| Rewrites
Rewrites -->|proxy| API
UI -.->|/events WS direct| WS
API --> Workflow
Workflow --> LLM
API --> Lair
API -->|verify tx| Solana
API -->|seed sprites| SpriteCatalog
Why this split:
- The static edge serves HTML/CSS/JS globally — zero build step, no framework.
- The Python runtime stays long-lived with a persistent volume for
lair.dband native WebSocket support for live agent telemetry. - The WebSocket bypasses the edge because CDN rewrite layers don't reliably tunnel WS — it connects to the runtime directly.
| Layer | Choice |
|---|---|
| Frontend | Vanilla JS + CSS (no React/Vue/build step). One static file per page. |
| Backend | FastAPI + uvicorn (Python 3.11). |
| State | SQLite (the lair) on a persistent volume. |
| Agents | Swarms for multi-agent orchestration. |
| Real-time | Native FastAPI WebSocket at /events with cross-tab localStorage sync. |
| Wallet | Phantom + @solana/web3.js (lazy-loaded from CDN). |
| Hosting | Static edge for HTML/CSS/JS + Python runtime with a persistent volume. |
| Build | None. git push and the deploy is live. |
Pet Forge ships as two services: a static edge for the frontend, and a Python runtime for the API + persistent storage.
- Auto-detects Python via
requirements.txt. - Mount a volume at
/dataso the lair survives redeploys (setAGI_HOME=/data/.aogi). - Configure provider credentials and CORS via environment variables — see
.env.example. - Expose a public domain.
- Flat static files. No build, install, or output commands.
- Edit the rewrite config to point
/api/*,/swarms/*,/setup,/task/*,/ledger/*,/teach,/lair/*,/healthz,/eventsat the runtime's domain. - Set the CORS env var on the runtime to the edge's public URL.
git push origin main triggers a coordinated redeploy on both.
| Method | Path | Purpose |
|---|---|---|
GET |
/setup |
Liveness + runtime config snapshot |
GET |
/api/agents |
Built-in + deployed Pet Agents |
POST |
/api/agents |
Create a Pet Agent |
PATCH |
/api/agents/{id} |
Update |
DELETE |
/api/agents/{id} |
Remove |
POST |
/task |
Submit a task to the swarm (returns task id) |
GET |
/task/{id}/receipt |
Final output + per-agent execution mode + Lies Ledger |
WS |
/events |
Live event stream (agent state, task progress) |
GET |
/api/pets?limit=500 |
Every skin in the lair + assignments map |
GET |
/api/pets/{id}/asset?state=idle |
Cacheable spritesheet (1y immutable) |
POST |
/api/pets/import_by_slug |
Server-side scrape of a community pet detail page by slug |
POST |
/api/pets/{id}/list |
List for sale (price_sol, seller_wallet) |
POST |
/api/pets/{id}/buy |
Confirm a buy with tx_signature. Polls Solana RPC, flips ownership. |
POST |
/api/pets/{id}/unlist |
Withdraw a listing |
POST |
/api/goblin/ask |
Quick chat with the floating-goblin chat panel |
┌─────────┐ ┌─────────┐
│ Seller │ 1. lists pet for X SOL │ Pet │
│ wallet │ ───────────────────────────────▶│ Forge │
└─────────┘ │ runtime │
▲ └────┬────┘
│ │
│ ▼
│ ┌─────────┐ 2. Phantom signs ┌─────────┐
│ │ Buyer │ SystemProgram │ Solana │
│ │ wallet │────.transfer───────▶│ mainnet │
│ └─────────┘ X SOL └────┬────┘
│ │
└─────────── 3. SOL lands ─────────────────┤
│
4. tx_signature
│
▼
┌─────────┐
│ Pet │ 5. verifies on-chain:
│ Forge │ pre/post lamports,
│ runtime │ correct from/to,
└────┬────┘ sufficient amount
│
▼
6. flips owner_wallet,
ownership = buyer
- Pet Forge never holds SOL. Buyer signs
SystemProgram.transfer(seller_wallet, lamports)directly in Phantom. - After signing, buyer hands the
tx_signatureback to the runtime, which callsgetTransactionagainst Solana RPC up to ~25s. If pre/post balances match an actual transfer of ≥ price from buyer to seller, the listing'sowner_walletis flipped. Otherwise the buy fails. - Zero platform fees, no escrow, no refunds.
Configuration lives in environment variables. The full annotated list is in .env.example — covers inference provider, model routing, Swarms backend selection, lair location, public-instance mode, marketplace RPC, and CORS allowlist.
Full annotated reference: .env.example.
Pet Forge accepts community pet packages:
- A
pet.jsonmanifest (name, slug, description, vibes, optional metadata) - A spritesheet (
.webp/.png/.svg/.jpeg, max 2 MB) — convention is 8 cols × 9 rows with each row a state and each cell a frame.
Imports are validated metadata-only — no uploaded content is ever executed. The spritesheet is base64'd and stored alongside the manifest in lair.db.
We do not bundle third-party assets and do not claim official integration with any external catalog. The auto-seeder on first /pets/ visit fetches each pet from its public detail page.
| Stage | Status | Highlights |
|---|---|---|
| MVP — The Burrow | ✅ Shipped | Goblin runtime, 7 built-in agents (Head, Scout, Digger, Tinker, Magpie, Guard, Scribe), SQLite lair, Lies Ledger v1, all 5 workflow shapes. |
| V1 — The Den | ✅ Shipped | Pet Agents (custom workers). Composite-skin Generator. Community-format import + auto-seed of 170+ pets. Marketplace with Phantom-wallet Solana payments (zero platform fees) — list, buy, download .pet.json, My Purchases filter. Click-to-chat with Sama. Cross-tab sync. Run Monitor. |
| V2 — The Warren | 🚧 Next | Voice input. Vector search across the lair. Hoard graph. OBS streamer mode. Cloud sync. Mobile companion. Mistake-memory retrieval. Public pet-pack export to .zip. |
PRs welcome. The shape is small enough that you can read every file in an afternoon — start at runtime/main.py (routes), runtime/agents/base.py (the agent loop), and pet-mode.js (frontend resolver).
If you're adding a new agent: drop a file in runtime/agents/ that subclasses BaseAgent and register it in runtime/agents/__init__.py. Existing agents are short — digger.py is ~80 lines.
If you're touching the marketplace: there is no test mode. Use a tiny SOL amount (e.g. 0.001 SOL) to walk the full list → buy → ownership-flip path, or point at devnet locally.
MIT — do whatever you want, attribution appreciated, no warranty.
- Swarms — the agent orchestration engine under the hood.
- Phantom + Solana — peer-to-peer settlement, no middleman.
- Goblin Sama — the default companion. Long may they hoard.
— Pet Forge: a goblin in the mutters, a professional in the artifact. —