Synopsis
Description
pome twin runs one digital twin on its own, outside a run. Reach for it when
you want to point an agent, a test, or curl at a twin and drive it by hand.
An ordinary run does not need it. pome run boots the twins its task
declares, and a hosted run provisions one per sandbox.
twin start
Start a twin as a long-lived foreground server. Press Ctrl-C to stop it.
Arguments
Options
A taken port fails before anything prints
The bind is the first thingtwin start does. When the port is already in use it
prints one line and stops:
POME_AUTH_TOKEN — and no
status file is written, so a failed start cannot leave a stale
.pome/twin-status.json behind for twin status to believe.
Examples
Serve the GitHub twin on the default port:twin start boots one twin, so say which:
twin new-seed
Print a new starter seed file for one or more twins, generated from the twin’s
own starting state. Edit what it prints rather than writing a seed from nothing —
the shape it emits is the shape the twin loads.
Arguments
Options
One file, three destinations
There is one shape, and the twin count decides it: one twin is flat, the twin’s own world with no wrapper; two or more is the per-twin envelope{ <twin>: { … } }. The same file then goes wherever you need it —
twin start --seed, sandbox create --seed, or
beside a task’s .md as <task>.seed.json.
What differs is where the twin’s name comes from. The sidecar has the task’s
## Config next to it, so it needs nothing; the two --seed doors have only the
command line, so a flat seed has to be paired with the name.
Examples
Read a twin’s starting state:twin status
Say whether the twin pome twin start last booted here is still running. Takes
no arguments, and no flags of its own beyond the
global flags, which are inert here.
It reads .pome/twin-status.json, probes the twin it names, and prints the
status line plus that twin’s paste-able env lines:
github twin — not running (stale .pome/twin-status.json) instead.
The probe is stricter than a plain liveness check: the health response has to
name that twin, so an unrelated dev server holding the port reads as not
running rather than as a green. A status file that cannot be read is one named
error, not a crash.
Exit status
See the canonical table.See also
pome sandbox— the hosted equivalent, with a bearer token and a lifetime.pome compile-seeds— generate a task’s seed from prose instead.- Digital twins reference — each twin’s starting state, printed by these commands.