Build your own world

Every twin boots with a world already in it: acme/api and one open bug on GitHub, a #general channel on Slack, an empty ledger on Stripe. That world is there so the first command works. It is not there because it looks like yours. A seed is how you replace it. Write your repositories, your threads, your customers, and the twin serves them to your agent as though they were real — same routes, same status codes, same recorded tape. This page is the whole job, from generating the file to proving every field of it landed.

A seed replaces the world. It does not merge into it.

This is the single most costly thing to get wrong, so it comes first.

A seed is the twin’s entire starting state, not a patch on top of the default one. Seed a GitHub world and acme/api is gone — anything your agent needs to find has to be in the file you wrote.

Measured on a local twin booted from the file further down this page:

$ API=$POME_GITHUB_REST_URL
$ AUTH="Authorization: Bearer $POME_AUTH_TOKEN"

$ curl -so /dev/null -w '%{http_code}\n' -H "$AUTH" \
    "$API/repos/northwind/payments"
200
$ curl -so /dev/null -w '%{http_code}\n' -H "$AUTH" \
    "$API/repos/acme/api"
404

There is no merge mode and no partial seed. A seed that omits labels boots a repository with no labels, not a repository with ours.

Generate the file; do not write it

pome twin new-seed github --out world.seed.json

pome twin new-seed prints the twin’s own starting state, computed from the twin’s declared world and normalised through the same parseSeed the twin runs at boot. Whatever it prints, the twin loads. Start from that and edit; do not compose one from the field names in a reference table. This is not a style preference. On 2026-08-26 three of the five seed examples published on this site could not boot the twin they were written for — repositories.0.owner missing on GitHub, primaryMailbox typed as a string on Gmail, issues.0.assignee null on Linear. Every one of them was correct the day it merged, and each was hand-typed. Copying one produced a 503 Failed to spawn twin pod twelve seconds later. Every seed block on this site is now generated and re-parsed in CI against its own twin. The generated file is a starting point with real bulk to it — with @pome-sh/cli@0.42.1: 82 lines for GitHub, 89 for Slack, 136 for Gmail, 270 for Linear, 14 for Stripe’s deliberately empty ledger. Cutting it down is the normal next step.

Seed file

Here is the GitHub file above, cut to one organisation, one repository and the one issue a triage task needs. It is what pome twin new-seed github printed, with the sample world’s names and rows replaced:

{
  "users": [
    { "login": "northwind", "type": "Organization", "name": "Northwind" },
    { "login": "dana", "type": "User", "name": "Dana Okafor" },
    { "login": "pome-agent", "type": "User", "name": "Pome Agent" }
  ],
  "repositories": [
    {
      "owner": "northwind",
      "name": "payments",
      "description": "Billing service for the Northwind storefront.",
      "private": false,
      "default_branch": "main",
      "collaborators": ["dana", "pome-agent"],
      "labels": [
        { "name": "bug", "color": "d73a4a", "description": "Something is not working" },
        { "name": "billing", "color": "0e8a16", "description": "Touches money" }
      ],
      "issues": [
        {
          "number": 1,
          "title": "Partial refunds replay the webhook forever",
          "body": "Every partial refund re-enqueues its webhook until the worker backs up.",
          "state": "open",
          "labels": [],
          "assignees": [],
          "comments": []
        }
      ],
      "pull_requests": []
    }
  ]
}

One twin is flat; two or more is the per-twin envelope. The file above is GitHub’s world with no wrapper around it — which also means it says nothing about which twin it is for, and that is why both --seed doors below take the twin’s name as well. Add a second twin and the file grows the envelope, one key each:

{
  "github": { /* the object above */ },
  "slack":  { /* what `pome twin new-seed slack` printed, edited the same way */ }
}

Write one file covering both in a single command:

pome twin new-seed github slack --out world.seed.json

Seeding two twins is not the same job as running them side by side against one agent — that half has its own guide, Two twins, one sandbox. JSON or YAML — both doors parse either. A _meta block, which pome compile-seeds writes into a task’s sidecar, is dropped before the twin sees it. Each twin’s own generated block, and the field names behind it, live on that twin’s page: github, stripe, slack, gmail, linear.

One file, both doors

The same world.seed.json boots a twin on your laptop and a hosted sandbox. No conversion, no second copy.

Local — no account
Hosted
REST

pome twin start github --seed world.seed.json

Name the twin. A one-twin file is flat, so it cannot say which twin it is for, and a file covering several does not say which of them to boot; only a hand-written envelope naming exactly one twin makes the argument optional. The command prints the twin’s URL and a bearer, and the boot line names the file:

Pome github twin listening at http://127.0.0.1:3333/s/standalone
Seed: world.seed.json (replaces the github twin's default).
POME_GITHUB_REST_URL=http://127.0.0.1:3333/s/standalone
POME_GITHUB_MCP_URL=http://127.0.0.1:3333/s/standalone/mcp
POME_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIs…
Health check (no auth): curl http://127.0.0.1:3333/healthz
Ctrl-C to stop.

pome sandbox create --twin github --seed world.seed.json

Same file, and --twin for the same reason. Repeat the flag for each twin the file covers. The CLI sends the shape the API wants — see pome sandbox for the flags, and Sandboxes for what one is and how long it lives.

curl -sX POST https://api.pome.sh/v1/sandboxes \
  -H "Authorization: Bearer $POME_API_KEY" -H 'Content-Type: application/json' \
  -d '{"twins":["github"],"seed":{"users":[…],"repositories":[…]}}'

Same rule on the wire: one twin takes the flat object, more than one takes the per-twin envelope, and the control plane decides from twins alone rather than from the seed’s contents. So a seed file drops straight into seed with nothing to unwrap; what the request adds is the twins array, which is where the names come from here. See Seeds.

The seed is parsed before a hosted sandbox is provisioned, so an unbootable world costs a 422 in well under a second rather than a spawn that fails. POST /v1/seeds/validate runs the same check and provisions nothing at all.

Check that every field landed

A twin that boots is not proof that your whole world arrived — until 2026-08-29 a typo’d field name could be silently dropped on three of the five twins. No longer, on your machine. Measured 2026-08-30 against @pome-sh/cli@0.42.1, a GitHub seed carrying isuses instead of issues refuses to boot, naming the key and its path:

$ pome twin start github --seed broken.seed.json
--seed broken.seed.json is not a seed this twin can boot: [
  {
    "code": "unrecognized_keys",
    "keys": [
      "isuses"
    ],
    "path": [
      "repositories",
      0
    ],
    "message": "Unrecognized key: \"isuses\""
  }
]

All five twins refuse the same way at twin start --seed since F-1689 landed. A wrong type was always refused everywhere — expected string, received undefined — so a local boot now vouches for every field name and type in your file.

The hosted door has not caught up yet. POST /v1/seeds/validate and sandbox create still run the previously pinned parsers (@pome-sh/sandbox-domains@0.2.8), on which github, slack and stripe accept an unrecognised key and silently drop it — the isuses seed above answers valid: true and boots a hosted world with no issues in it. Until the pin moves, two habits close that gap: boot the seed locally first, where the refusal above catches the typo for free, and read your hosted collections back — an empty array where you wrote rows is a dropped key. F-1775 tracks the pin move.

Seed file, or task sidecar

One file, two destinations. pome twin new-seed <twin> writes it either way, and the shape follows the twin count rather than where it is going.

	Seed file	Task sidecar
Named	anything — `world.seed.json`	`<task>.seed.json`, beside the task’s `.md`
Read by	`pome twin start --seed`, `pome sandbox create --seed`	`pome run`, and hosted runs of that task
Twin named by	you, on the command line	the task’s `## Config` block

Both are flat for one twin and the per-twin envelope from two up, so a file written for one destination works at the other. What differs is only the last row: a sidecar has the task’s ## Config beside it, while a seed file travels alone and so has to be handed the name. Replace-not-merge applies to both, and both accept JSON or YAML. A task is not required to seed a world. A hosted sandbox created with twins and seed and no task records no task at all, which is what a bring-your-own-eval harness wants: you drive the agent, and you score the tape from the twin’s own /_pome/events.

Write a task

Turn the world you just built into a graded exam — criteria, [code] checks, and why a criterion the seed already satisfies leaves the denominator.

pome twin

Every flag on twin new-seed, twin start and twin status.

Seeds over REST

The wire shape, POST /v1/seeds/validate, and the error vocabulary a client branches on.

Digital twins

Each twin’s generated starting state, its declared checks, and what it serves.

Grade your agent

Run more than one twin

Worked examples

Build your own world

A seed replaces the world. It does not merge into it.

Generate the file; do not write it

Seed file

One file, both doors

Check that every field landed

Seed file, or task sidecar

Next

Write a task

pome twin

Seeds over REST

Digital twins

​A seed replaces the world. It does not merge into it.

​Generate the file; do not write it

​Seed file

​One file, both doors

​Check that every field landed

​Seed file, or task sidecar

​Next

Write a task

pome twin

Seeds over REST

Digital twins

A seed replaces the world. It does not merge into it.

Generate the file; do not write it

Seed file

One file, both doors

Check that every field landed

Seed file, or task sidecar

Next