Quickstart

poema cloud is managed hosting for the agents your organization runs, of every kind: research, support, data, operations, coding. Your agents run in instances: isolated environments that poema cloud runs for you, each from poema's Linux base image and a command. You create, suspend, resume and fork instances through its API: from Python, from a shell, from Claude Code or another MCP client, or over HTTP. Or deploy an agent from its git repository on the dashboard: Deploy from git.

The API, the SDK and the CLI call an instance a task (kind: Task, create_task), and the MCP server's tools a sandbox (sandbox_create). The code on these pages uses those names as they are.

1. Sign in

Sign in on the home page with GitHub or Google. poema cloud is in a private beta, which lets people in a few at a time: a new account starts on the waitlist, and the dashboard opens once it is let in.

2. Make a key

On the dashboard's API keys page, make a key. It is shown once, so keep it. It starts with poema_ns_ and your namespace, and reaches that namespace alone.

3. Install the SDK

The Python SDK needs Python 3.9 or later and nothing else, and brings poema-mcp, the MCP server. It is not on PyPI: this site carries its wheel.

The Python package is coming; the HTTP API works today.

4. Your first instance

With your key in place of poema_ns_..., run this in a shell:

export POEMA_URL=https://127.0.0.1:7070
export POEMA_API_KEY=poema_ns_...

~/.venvs/poema/bin/python - <<'EOF'
from poema import Poema

p = Poema()
t = p.create_task("hello", ["sh", "-c", "echo hello"], gateway="default")
print(t.wait_exit(timeout=600), t.logs())
t.suspend()   # its files stay; t.resume() goes on
EOF

gateway="default" is your namespace's Gateway, which reaches package registries and git hosts; without one an instance has no network. The dashboard lists the instance, and the Python SDK page shows what else it can do.

5. Claude Code

Let Claude Code create and work in instances through the MCP server:

claude mcp add poema -e POEMA_URL=https://127.0.0.1:7070 -e POEMA_API_KEY=poema_ns_... -- poema-mcp

Claude Code has to find poema-mcp: put ~/.venvs/poema/bin on its PATH, or give the full path. The poema-mcp page lists its tools.