runtm

name runtm description Runtm (Runtime) Cloud CLI for AI agents. Full cloud-API surface: sessions (CRUD + search + files + upload/download + env + deploy + approvals + capability loading + lifecycle + history + events), the agent roster (identity + instructions + evaluation rubric + budget + scorecard + run grades), scheduled agents (cron automation + run-now), org templates (CRUD + build + context + guardrails + owning groups + secrets), guardrail content (allowlist rules, hooks, network rules), skills lifecycle (import, discover, resync, lock), deployments, GitHub App installations, groups, activity telemetry, secrets, instructions, LLM provider keys, external integrations (MCP, tools, Slack, GitHub, Linear, Email). Trigger on: runtm, runtime, runtm cloud, runtime cloud, runtm session, runtime session, cloud sandbox, integration, integrations, mcp, skill, provider key, scheduled agent, cron, automation, agent roster, evals, evaluation, scorecard, guardrail, approvals, deployment, build an agent, create an agent, support agent. metadata {"version":"0.11.0","repository":"https://github.com/runtm-ai/runtm","tags":"runtm,runtime,cli,sandboxes,coding-agents"} Runtm (Runtime) Cloud CLI for Runtm Cloud -- the hosted control plane for cloud sandboxes. When the user says "runtime" or "runtm" they mean this tool. The binary is runtm-api (separate from the pip runtm CLI which handles local dev). This CLI talks to the hosted cloud API only (through https://app.runtm.com/api/cloud/... , which proxies to backend /api/... ). It covers the same operations the dashboard does, so AI agents can do anything a human does in the UI: create templates, fix broken ones, launch sessions, inspect files, manage secrets, deploy. Full API reference: https://docs.runtm.com/cloud-api Most common path: template → session → run commands The everyday loop is create a template, boot a session from it, then connect or exec into it . Memorize this: # 1. Create a template from a repo. --skip-agent does a clone-only build (no AI # step -> fast) and implies --build, so the build kicks off immediately. runtm-api template create \ --display-name "NuvoOS Dev Environment" \ --github-repo runtm-ai/landing-page \ --github-branch main \ --tier standard \ --name template \ --skip-agent # -> {"id": "28f6e6e6-d73d-4f21-8b1f-312e17e8f47b", "build_status": "pending", ...} # 2. Wait until the template is ready (only "ready" templates can boot sessions) runtm-api template get 28f6e6e6-d73d-4f21-8b1f-312e17e8f47b | jq -r .build_status # 3. Boot a session from the template runtm-api session create --template-id 28f6e6e6-d73d-4f21-8b1f-312e17e8f47b # -> {"id": "a6414511-4430-4e1f-8c51-8ea8824dadec", "state": "creating", ...} # 4a. Attach an interactive shell (raw PTY; requires a TTY on stdin) runtm-api session connect a6414511-4430-4e1f-8c51-8ea8824dadec # 4b. Or run one command non-interactively and capture its output + exit code runtm-api session exec a6414511-4430-4e1f-8c51-8ea8824dadec -- pwd # 4c. Parsing the output? Use --json for separated streams and no shell noise. runtm-api session exec a6414511-4430-4e1f-8c51-8ea8824dadec --json -- npm test # -> {"stdout": "...", "stderr": "...", "exit_code": 0} Use session connect when a human wants a live shell; use session exec for scripted, one-shot commands. Both need the sessions:terminal scope, and both auto-resume a paused sandbox. See the runtm-sessions skill for the full recipe. Always pass --json to session exec when you are going to parse the output. The default is the raw PTY stream, which merges stderr into stdout and carries shell startup noise (mise/nvm banners and the like) that you would otherwise have to filter out with grep -v . --json captures the two streams separately and strips PTY carriage returns. To parameterize a template, declare session arguments with --session-arg (each becomes an env var in the session); supply values at boot with session create --template-id <uuid> --template-args KEY=VALUE . See the runtm-templates skill. Other common path: building an agent The loop above is for driving a sandbox yourself . When the ask is "build me an agent that does X" (support triage, on-call, research, code review), the shape is different and the order matters. Read the runtm-build-agent skill first. The one thing to know before you start: every capability an agent has hangs off one template. trigger -> roster agent -> template -> { skills, MCP servers, tools, guardrails, context } -> session So a roster agent without --template can do nothing special, a skill that is never attached to that template is never loaded, and an attachment made after the last build does nothing until you rebuild. All three fail silently . Create the template, attach everything, verify with template get , then build once . Note that template create --skip-agent implies --build , so the fast path above will bake an empty template if you meant to attach skills to it. Quick Reference Sessions Task Command List sessions runtm-api session list Launch agent + prompt runtm-api session launch --prompt "<task>" Create blank session runtm-api session create --agent claude-code Create session from org template runtm-api session create --template-id <uuid> Boot template session with arg values runtm-api session create --template-id <uuid> --template-args KEY=VALUE Attach interactive terminal (PTY) runtm-api session connect <id> Run one command (scripted) runtm-api session exec <id> -- <command> Run one command, parseable output runtm-api session exec <id> --json -- <command> Stream prompt runtm-api session prompt <id> "<task>" Stream live event bus runtm-api session events <id> Poll status (last_prompt) runtm-api session status <id> Get canonical detail runtm-api session get <id> Prompt history runtm-api session history <id> Cancel a running prompt runtm-api session prompt-cancel <id> Rewind to a prior prompt runtm-api session prompt-rewind <id> --to-index N Inspect workspace state runtm-api session workspace-state <id> Pause / resume / rename runtm-api session pause|resume|rename <id> [...] Bump idle timer runtm-api session heartbeat <id> Change visibility (inside the org) runtm-api session visibility <id> private|team Share a preview outside the org runtm-api session share create <id> --email <addr> [--port N] List who a preview is shared with runtm-api session share list <id> [--port N] Revoke a preview share runtm-api session share revoke <id> <share_id> List my own preview URLs runtm-api session previews Per-session instructions runtm-api session instructions get|set <id> ... Collaborators runtm-api session collaborators <id> Start dev server runtm-api session run-server <id> [--port N] Search sessions with filters runtm-api session search -q "<text>" [--agent ...] [--template ...] [--team-mode] Run's evaluation verdict runtm-api session grade <id> List approval gates runtm-api session approvals list <id> Approve / reject a gate runtm-api session approvals resolve <id> <approval_id> --approve|--reject [--note "..."] Hot-load skills into a running session runtm-api session load-skills <id> <skill_id...> Hot-load MCP servers runtm-api session load-mcps <id> <mcp_id...> Hot-load tools (by provider slug) runtm-api session load-tools <id> <slug...> Tools loaded in a session runtm-api session tools <id> Files: read/write/list runtm-api session file read|write|list <id> ... Files: search/mkdir/rename/delete runtm-api session file search|mkdir|rename|delete <id> ... Files: binary upload/download runtm-api session file upload|download <id> <path> ... Env vars: get/set/delete runtm-api session env get|set|delete <id> ... Env vars: detect / detected runtm-api session env detect|detected <id> Open PR with changes runtm-api session git <id> create_branch_and_pr --pr-title "..." Generic git ops runtm-api session git <id> <op> [flags] Deploy: info/scaffold/validate/preflight runtm-api session deploy info|scaffold|validate|preflight <id> Deploy: run (SSE) runtm-api session deploy run <id> Destroy session runtm-api session destroy <id> Org templates (full lifecycle) Task Command List templates runtm-api template list Get template detail (incl. attached skills + build staleness) runtm-api template get <tmpl_id> Create new template runtm-api template create --display-name "..." --github-repo owner/repo Create + clone-only build (no AI step) runtm-api template create --display-name "..." --github-repo owner/repo --skip-agent Declare session args (create/update) runtm-api template create ... --session-arg KEY=DEFAULT --session-arg '{"key":"ENV","type":"select","options":["dev","prod"]}' Update metadata runtm-api template update <tmpl_id> --display-name "..." Delete template runtm-api template delete <tmpl_id> --yes Trigger build runtm-api template build <tmpl_id> Stream build logs runtm-api template build-logs <tmpl_id> Past build logs runtm-api template build-logs-history <tmpl_id> Fix a broken template (open session) runtm-api template fix-session <tmpl_id> Save fix-session as new snapshot runtm-api template save-snapshot <tmpl_id> --session <session_id> Discover GitHub repos eligible runtm-api template repos List template secrets runtm-api template secrets list <tmpl_id> Set template secrets runtm-api template secrets set <tmpl_id> KEY value [KEY value ...] Delete a template secret runtm-api template secrets delete <tmpl_id> KEY Skills/MCP attached to a template runtm-api template skills|mcp <tmpl_id> (or skills|mcp list --template <tmpl_id> ) Attach a skill/MCP to a template runtm-api skills|mcp attach <id> --template <tmpl_id> Template context (instructions) runtm-api template context get|set|resolve <tmpl_id> Template guardrails runtm-api template guardrails list|create|update|delete|resolve <tmpl_id> ... Owning group / auto-rebuild cron runtm-api template update <tmpl_id> --owner-team <team_id> | --rebuild-schedule '0 6 * * *' Verify a template actually loads your skills The most common template mistake is creating skills and never attaching them, so sessions boot without the behaviour you wrote. template get answers this inline — no second call needed: runtm-api template get <tmpl_id> | jq '{ skills: [.skills[].name], stale: .attachments_changed_since_build }' skills: [] means nothing is attached, however many skills exist in the org. Fix with runtm-api skills attach <skill_id> --template <tmpl_id> . stale: true means the attachments changed after the last build, so the snapshot sessions boot from is behind the config. Fix with runtm-api template build <tmpl_id> . Each entry carries attached_via : template (attached directly), repo (via one of the template's repos), or all (org-wide). Three commands give the same skills answer, so reach for whichever you thought of first: runtm-api template get <tmpl_id> | jq .skills # inline, plus staleness runtm-api template skills <tmpl_id> # template-first runtm-api skills list --template <tmpl_id> # skills-first Agent roster (named agents + the evaluation loop) Named agents with identity, system instructions, session defaults, an evaluation rubric, and a budget. This is the entity the dashboard's Agents page manages. Omit --type for the roster; --type slack|github|linear|email manages that platform's trigger integrations instead. Task Command List roster agents runtm-api agents list Create (headless) runtm-api agents create --name X --instructions '...' [--template <slug>] Edit identity/defaults runtm-api agents update <id> --instructions '...' --template <slug> [--clear-template] Set the evaluation rubric runtm-api agents update <id> --evaluator-criteria '{"objective":"...","checks":["..."]}' Set task values + budget runtm-api agents update <id> --economics '{"tasks":{"triage":{"value_usd":10}},"budget":{"monthly_usd_cap":50}}' Per-agent scorecard runtm-api agents scorecard --days 30 One run's verdict runtm-api session grade <session_id> Trigger credential refs runtm-api agents trigger-credentials Delete runtm-api agents delete <id> --yes (delete its triggers first) Linear trigger (headless) runtm-api agents create --type linear --linear-api-key lin_api_... --service-user <user_id> Email trigger (headless) runtm-api agents create --type email --name X --agent-id <roster_agent_id> The evaluation loop: set evaluator_criteria on the agent, every completed run is graded against it, session grade reads one verdict, agents scorecard aggregates hit rate, spend, value, and budget. Without a rubric nothing is graded and the scorecard shows zeros. Guardrail content (allowlist rules, hooks, network rules) guardrails limits|allowlist manage org settings. The rules themselves are directives that attach to templates, repos, or the whole org, exactly like skills: | Task | Command |