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.

Self-hosting gives you a fully offline Pome setup — twin and CLI on your own machine or CI runner, with zero dependency on pome.sh cloud. You control the data, the reset cadence, and the LLM provider used for [P] criterion evaluation. There is no account to create and no API key to manage.

​
Prerequisites

  • Docker with Compose v2
  • Bun ≥ 1.3 or Node ≥ 20
  • git
1

Clone the repo

git clone https://github.com/pome-sh/pome.git && cd pome
2

Start the twin

docker compose up -d
On first boot, the twin auto-generates a bearer secret and writes it to .pome-data/secret. Subsequent starts reuse the same secret.
If docker compose up fails to pull the image, run docker login ghcr.io first. The image requires authentication to GitHub Container Registry.
3

Verify the twin is running

curl http://127.0.0.1:3333/healthz
You should see:
{"status":"ok"}
4

Install the CLI

npm install -g pome
Verify the installation:
pome version
5

Run a scenario

pome run examples/scenarios/ --agent "bun run start"
The CLI seeds the twin with the scenario’s ## Setup state, runs your agent, scores the criteria, and writes trace artifacts to runs/.

​
Resetting twin state between runs

The CLI handles seeding automatically — before each run it posts the scenario’s ## Setup JSON to the twin’s seed endpoint, which drops and recreates all state. You do not need to reset the twin manually between pome run invocations. If you want to reset the twin manually — for example, to poke it interactively or to clear state after a standalone bun run start against the docker-compose twin — use the CLI command: 
pome twin reset

​
Configuration

Create a .pome.json file in your project root to configure the CLI’s mode and twin connection: 
{
  "mode": "oss",
  "twins": {
    "github": { "url": "http://localhost:3333" }
  }
}
FieldPurpose
mode"oss" for self-host (no cloud API calls); "hosted" for the pome.sh control plane
twins.github.urlBase URL of the local twin
The CLI walks up from the current directory to find .pome.json, so you can place it at the project root and run pome from any subdirectory.

​
Bring your own LLM for [P] evaluation

[P] criteria require an LLM judge. Set one of the following in your shell or CI environment: Auto-detected providers: 
export ANTHROPIC_API_KEY=sk-ant-...   # uses Anthropic's endpoint automatically
export OPENAI_API_KEY=sk-...          # uses OpenAI's endpoint automatically
Any OpenAI-compatible endpoint: 
export POME_LLM_BASE_URL=https://openrouter.ai/api/v1
export POME_LLM_API_KEY=sk-or-...
export POME_LLM_MODEL=anthropic/claude-haiku-4-5
Fully offline with Ollama: 
export POME_LLM_BASE_URL=http://localhost:11434/v1
export POME_LLM_MODEL=llama3.1
# POME_LLM_API_KEY can be omitted for Ollama
The CLI talks directly to whatever endpoint you configure. The pome.sh cloud never sees your key or the LLM output.

​
When to use hosted instead

Self-hostHosted
CostFreeUsage-based
PrivacyFully localTraces stored on pome.sh
SetupDocker + CLI installAccount + API key
Offline capableYesNo
Team dashboardNoYes
Trace historyLocal filesystemCloud dashboard
Managed twinsNoYes — no infra to maintain
Self-host is the right choice when you need full data locality, want to run air-gapped, or are evaluating Pome before committing to a plan. Switch to hosted when you want a shared trace history across your team, a managed twin, or no infra to maintain.
Pome is licensed under AGPL-3.0. Internal use — including running Pome inside your company to evaluate your own agents — is free with no obligation. If you modify Pome and serve those modifications over a network to other users, AGPL §13 requires you to publish the modified source. Your agents’ code is not affected; AGPL reaches the modified Pome, not the application code that calls Pome’s API. Contact licensing@pome.sh for dual-licensing inquiries.