poema cloud

Concepts

Instances

An instance runs your agents: its command and whatever you start in it, with the Workspaces, Gateway and Model it uses, on poema's base image (Debian with git and bash) or the Python and Node runtimes (Deploy from git). Each instance is isolated: its own environment, its own network rules, nothing shared with other instances. Its phase is Pending until it runs, then Running, Suspended, or Failed when it could not start. Its command exiting does not end it: the instance stays up for its files and commands until it is suspended or deleted, or its session ends.

Its files are in /workspace, which is kept when the instance is suspended and copied when it is forked: keep your work there. A Workspace resource declares git repositories to clone into it before the command starts.

Suspend and resume

A suspended instance stops: it uses no compute and does not count as running. Its memory is kept with its files, and a resume restores both in milliseconds, so its processes carry on where they stopped. Its session's clock starts again at every resume.

Fork

A suspended instance forks into new ones, up to 100 in one call, each on a copy of its /workspace: to try several approaches from one point. A fork's processes are new, its command starting again on the copied files, and its label poema.dev/forked-from names its source. With memory=True in the SDK each fork gets a copy of its memory too, and its processes go on where they were, as after a resume: what they drew at random, requests in flight and timers are then the same in every fork. The source stays suspended until it is resumed.

Egress and Gateways

An instance's network is closed: it reaches only the hosts its Gateway allows, and everything else is denied. The hosts it reaches, and those it is denied, go in its activity (poema describe task NAME). Your namespace has a Gateway default, which allows the free tier's hosts below; an instance without a gateway has no network at all. A Gateway of your own lists hosts, *.example.com for every subdomain, each on one port or any, and reaches only those the free tier allows too:

kind: Gateway
metadata: {name: pypi-only}
spec:
  egress:
    allowlist:
      hosts:
        - {host: pypi.org, port: 443}
        - {host: files.pythonhosted.org, port: 443}

Models through the broker

A Model names a provider (anthropic, openai or google), a model, and the secret that holds your key for it. An instance bound to a Model calls the provider through poema's broker, which adds the key on the way out, so the key never enters the instance: there ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY, or OpenAI's or Gemini's, point the stock SDKs at the broker with the instance's own token. Each call's model and token counts go in the instance's activity. Model calls need no Gateway. Secrets are write-only: nothing reads a value back.

poema secret set anthropic api-key=sk-ant-...
poema apply -f - <<'EOF'
kind: Model
metadata: {name: claude}
spec:
  provider: anthropic
  model: claude-sonnet-5-5
  secretKey: {name: anthropic, key: api-key}
EOF

An instance names it with model: {name: claude}, or model="claude" in the SDK.

The free tier

  • 3 instances running at once, with 4 vCPUs and 8 GiB of memory between them. An instance that would go past these waits, Pending with the reason QuotaExceeded, until another stops.
  • Sessions of up to 60 minutes. At its end an instance is suspended, not deleted: resume it for another. One left suspended for 14 days is deleted.
  • 100 vCPU-hours of compute a month, renewed on the first (UTC). Past them, instances wait for the next month, and running ones are suspended.
  • 12 objects kept: instances, suspended ones too, Workspaces, Gateways, Models and secrets.
  • The base image and the Python 3.12 and Node 22 runtimes (Deploy from git): an instance that names another image is refused.
  • Egress on port 443 to package registries and git hosts: github.com, api.github.com, codeload.github.com, objects.githubusercontent.com, raw.githubusercontent.com, gitlab.com, registry.npmjs.org, pypi.org, files.pythonhosted.org, proxy.golang.org, sum.golang.org, index.crates.io, static.crates.io, deb.debian.org.
  • Models on your own provider key, through the broker. There is no model credit.
  • Workspaces are not backed up during the beta.

The dashboard's Usage page shows how much of each you have used.