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.

A session is a provisioned twin instance with its own SQLite database, seeded from your scenario’s ## Setup block and ready for exactly one agent run. When the run finishes, the twin state is discarded and the run artifacts are retained. The next run gets a fresh session with a clean slate.

​
Session lifecycle

1

Session provisioned

The CLI boots the twin (locally via Docker, or on a hosted pod) and applies the scenario seed to its SQLite database. The session moves from provisioning to ready once the twin passes its health check.
2

Agent runs

The CLI launches your agent process with the twin URL in POME_GITHUB_REST_URL. Every HTTP call the agent makes is recorded by the twin’s middleware. The session state is running.
3

Pome evaluates

Once your agent exits (or the timeout fires), the CLI reads the twin’s final SQLite state and runs the evaluator against your scenario’s success criteria. The score and per-criterion results are written to score.json.
4

Session tears down

The twin state is discarded entirely. Run artifacts (score.json, tool_calls.jsonl, state_initial.json, state_final.json, meta.json) are retained on disk (self-host) or uploaded to S3 (hosted). The session moves to done.

​
Self-host vs hosted sessions

The session lifecycle is the same in both modes. What differs is how the CLI provisions the twin. Self-host: the CLI talks directly to a local twin container running on your machine. There is no session provisioning API call and no session_id. The twin URL is always http://127.0.0.1:3333 (or whatever port you configured). The CLI reseeds the twin’s state from the scenario’s ## Setup block before each run automatically. Hosted: the CLI calls POST /v1/sessions to provision a fresh twin pod on Pome’s infrastructure. The response includes a twin_url and a short-lived agent_token scoped to that session. The CLI passes both to your agent process. When the run completes, the scored result is recorded and the pod is torn down.

​
Session states

StateMeaning
provisioningTwin is booting and seed is being applied.
readyTwin passed its health check; waiting for the agent to start.
runningAgent is active and making calls to the twin.
doneRun completed and artifacts have been written or uploaded.
expiredSession hit its TTL before the run completed. Artifacts may be partial.
failedTwin failed to boot or the seed could not be applied.

​
Session isolation

Each session has its own SQLite database, initialized from zero and seeded from your scenario. There is no shared state between sessions and no leftover data from previous runs. Two concurrent sessions for the same scenario will each see an identical starting state and will never observe each other’s mutations. On self-host, the twin container’s database is wiped and reseeded before every pome run invocation. On hosted, each session runs in its own pod.

​
Session TTL

Hosted sessions expire automatically after 30 minutes. The expires_at timestamp is included in the POST /v1/sessions response. If your agent is still running when the TTL fires, the session moves to expired and the twin stops accepting requests. You can extend the TTL at scenario level by setting a longer timeout in ## Config, up to your plan’s maximum.
On hosted, use pome sessions list to see all active sessions for your team and pome sessions kill <session-id> to tear one down early. This is useful when a run hangs and you want to free up quota without waiting for the TTL.

​
Next steps

  • Sessions API reference — full request/response shapes for POST /v1/sessions, GET /v1/sessions, and DELETE /v1/sessions/{id}