Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pome.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Hosted mode

pome run --hosted executes a scenario against the hosted control-plane at https://pome-cloud-control-plane.fly.dev. The CLI:
  1. POSTs /v1/sessions to spawn a real twin pod on Fly.
  2. Runs your agent against the spawned twin via the returned twin_url and agent_token.
  3. Scores the run locally using the deterministic evaluator.
  4. POSTs the score + trace blobs to /v1/sessions/{id}/result.
  5. Prints a dashboard URL for the persisted run.
Your LLM provider key — if any — never crosses the wire (BYOK Flavor #1). The CLI never uploads agent_stdout.

​
Quickstart

Sign in through Clerk and let the control-plane mint a team API key: 
pome login
pome run scenarios/01-bug-happy-path.md --hosted
CI can still use an explicit key: 
export POME_API_KEY=pme_yourkey
pome run scenarios/01-bug-happy-path.md --hosted

​
Auth resolution

The CLI looks for credentials in this order:
  1. POME_API_KEY env var (CI / one-off / direnv).
  2. ~/.pome/credentials.json written by pome login (persistent).
If neither is set, hosted mode fails fast with a friendly message before any session is spawned. You can override the cloud base URL with POME_API_URL=https://staging... (env) or --api-url (flag). pome login also accepts --dashboard-url https://pome.sh while the production domain is still settling.

​
V1 scope notes

  • Only [D] (deterministic) criteria are scored. [P] (LLM-judge) criteria are silently skipped.
  • The twin starts from its default seed (acme/api, three labels, issue #1). Custom seed override is not yet supported in hosted mode — scenario ## Seed State blocks are honored in self-host but ignored in hosted (the CLI sends scenario_source only, not seed). Coming in V1.1.
  • Single twin (github) only.
  • pome login uses Clerk for human auth, then stores the same pme_... runtime credential that hosted mode already sends as X-API-KEY.

​
Exit codes

CodeMeaning
0All scenarios passed passThreshold.
1At least one scenario scored below threshold.
2Twin or orchestrator error (network, 5xx, twin spawn failed).
3Auth error (401/403). Re-mint your key.
4Quota exceeded. Upgrade plan or wait for reset.
5Usage error (bad flags, missing files).

​
Differences from self-host

AspectSelf-hostHosted
Twin locationIn-process (Hono)Fly Machine spawned per session
AuthRandom per-run JWTHS256 JWT signed by control-plane
SeedScenario’s ## Seed StateTwin’s defaultSeedState()
Result storageruns/<slug>/<run_id>/ only+ cloud row + trace blobs in Supabase Storage
CleanupServer stops at end of runDELETE /v1/sessions/ on completion
The agent’s environment variables are identical in both modes (POME_GITHUB_REST_URL, POME_AUTH_TOKEN, etc.) — your agent code does not need to know which mode it’s running in.