/files

name: runtm
description: "Runtm (Runtime) Cloud, the platform where operations teams create and run AI agents, and its CLI runtm-api. Use for anything about runtm, runtime, runtm cloud, sessions, cloud sandboxes, templates, the agent roster, evaluation rubrics and scorecards, scheduled agents and cron, triggers (Slack, Linear, GitHub, Email, WhatsApp, SMS), skills, MCP servers, tool providers and integrations, guardrails, approvals, deployments, or when asked to build, create, or fix an agent (support agent, risk agent, underwriting agent). The method and every recipe live in the docs at https://docs.runtm.com/llms.txt; this file tells you how to read them and the few rules that fail silently."
metadata:
  version: "0.12.0"
  repository: https://github.com/runtm-ai/runtm
  tags: runtm,runtime,cli,agents,sandboxes

Runtm (Runtime) Cloud

Runtime is where teams create and run agents that have a job, a way to measure success, tools, a runbook, triggers, and guardrails. The binary is `runtm-api` (not the pip `runtm` CLI, which handles local dev). It talks only to the hosted API at `https://app.runtm.com/api/cloud/...` and covers everything the dashboard does, so you can do anything a person does in the UI.

Read the docs first

The documentation is the source of truth and is written to be read by you. Do not work from memory of this file when a page exists.

1. Fetch `https://docs.runtm.com/llms.txt`. It lists every page as `[Title](url.md): description`. The description says when to read the page and what you can do after; pick by description. 2. Fetch the page as markdown by appending `.md` to its URL, for example `https://docs.runtm.com/build/give-it-tools.md`. 3. Every dashboard step on a Build or Guides page carries its CLI equivalent as a hidden comment: `{/* cli: runtm-api ... */}` and `{/* cli-verify: ... */}`. Lift those commands; they are verified against the CLI source. 4. No fetch tool in this sandbox? `runtm-api docs` prints `llms.txt`, and `runtm-api docs <path>` prints one page (`runtm-api docs build/give-it-tools`).

Where things are:

| You need | Read | |---|---| | The method for building any agent (six steps, in order) | `build/overview` and its six pages | | A complete agent to copy (payments support, fraud and risk review, merchant underwriting) | `guides/overview`, `guides/payments/*` | | One task (connect Stripe read-only, add a KYB provider, add an MCP server, route a Linear team, test a schedule, request an approval, delegate to another agent) | `guides/recipes/*` | | Multi-agent: one agent handing work to subagents behind human approvals | `guides/recipes/delegate-to-another-agent`, `guides/payments/multi-agent-underwriting` | | Driving a session, template lifecycle, debugging a stuck run, API patterns | `cloud-api/patterns/*` | | Every command, flag, scope, and error | `cloud-api/agent-cli`, `cloud-api/scopes`, `cloud-api/errors`, then the endpoint pages |

The method: capable first, then safe

An agent is built in six steps and the order matters. Steps 1 to 4 give it context and ability, step 5 proves it on seeded cases with read-only credentials, step 6 adds guardrails written from what the passing runs did. Never start with guardrails; a rule written before the first run is a guess, and on an unproven agent it hides capability gaps behind stalls.

1. **Define the job**: roster agent with description, system instructions, default template, coding agent. 2. **Measure success**: evaluation categories (when to use, pass or fail criteria, tags, human cost and time), monthly budget (observe-only). Without a category nothing is graded. 3. **Give it tools**: the template carries tool providers, MCP servers, secrets, repos. Credentials resolve agent, then personal, then org-wide. 4. **Define how it works**: a runbook skill, the instruction layers, a trigger pointed at a test channel or a disabled schedule. 5. **Prove it works**: run seeded cases, read `session grade` and `agents scorecard`, tighten one thing at a time. 6. **Add guardrails and approvals**: allow, ask, deny rules from observed commands, network rules, `runtm-approval` at the runbook step that must wait.

Read `build/overview.md` before creating or changing an agent.

Two golden paths

**Drive a sandbox yourself** (create a template, boot a session, run commands):

runtm-api template create --display-name "Dev env" --github-repo owner/repo --skip-agent   # --skip-agent = clone-only build, implies --build
runtm-api template get <template_id> | jq -r .build_status                                  # wait for "ready"
runtm-api session create --template-id <template_id>
runtm-api session exec <session_id> --json -- npm test                                      # {"stdout","stderr","exit_code"}
runtm-api session connect <session_id>                                                      # live PTY for a human

**Build an agent** (every capability hangs off one template):

trigger -> roster agent -> template -> { skills, MCP servers, tools, guardrails, context } -> session

Create the template, attach skills and MCP servers, verify with `template get`, build once, then create the roster agent pointing at the template, connect a test trigger, run the seeded cases, and only then add guardrails. Full recipe: `build/overview.md`; full worked examples: `guides/payments/*.md`.

Rules that fail silently

• **Attached is not built.** Skills, MCP servers and guardrail rules attached after the last build are not in the snapshot. `template get | jq '{skills:[.skills[].name], stale:.attachments_changed_since_build}'` tells you; `template build` fixes it. `template create --skip-agent` implies `--build`, so attaching afterwards makes the template stale immediately.
• **A roster agent without `--template` runs on a bare sandbox** with no tools, skills or secrets.
• **A tool connection reaches a session only if an attached skill lists the provider in `requires.integrations`**, unless the c