| name | runtm |
| description | Runtm (Runtime) Cloud CLI for AI agents. Full cloud-API surface: sessions (CRUD + files + env + deploy + lifecycle + history + events + visibility + collaborators), org templates (CRUD + build + fix-session + snapshot + secrets), activity telemetry, secrets, instructions, guardrails, integrations. Trigger on: runtm, runtime, runtm cloud, runtime cloud, runtm session, runtime session, cloud sandbox. |
| metadata | {"version":"0.8.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:
runtm-api template create \
--display-name "NuvoOS Dev Environment" \
--github-repo runtm-ai/landing-page \
--github-branch main \
--tier standard \
--name template \
--skip-agent
runtm-api template get 28f6e6e6-d73d-4f21-8b1f-312e17e8f47b | jq -r .build_status
runtm-api session create --template-id 28f6e6e6-d73d-4f21-8b1f-312e17e8f47b
runtm-api session connect a6414511-4430-4e1f-8c51-8ea8824dadec
runtm-api session exec a6414511-4430-4e1f-8c51-8ea8824dadec -- pwd
Use session connect when a human wants a live shell; use session exec for scripted, one-shot commands (it streams stdout and exits with the command's exit code). Both need the sessions:terminal scope. See the runtm-sessions skill for the full recipe.
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.
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> |
| 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 | runtm-api session visibility <id> private|team |
| 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] |
| 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> ... |
| 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 | 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> |
| Attach a skill/MCP to a template | runtm-api skills|mcp attach <id> --template <tmpl_id> |
Activity (telemetry)
| Task | Command |
|---|
| Personal summary | runtm-api activity summary |
| Recent prompts | runtm-api activity recent-prompts --limit 20 |
| Daily breakdown | runtm-api activity daily --days 7 |
| Per-session usage | runtm-api activity session-usage <id> |
| Team summary | runtm-api activity team-summary |
| Team activity over time | runtm-api activity team-activity --days 7 |
| Team members | runtm-api activity team-members |
Secrets / Instructions / Guardrails / Integrations / Plan
| Area | Commands |
|---|
| Secrets | runtm-api secrets list|set|delete|resolved [--team] |
| Instructions | runtm-api instructions get|set [--org-scope] [--text "..."|--clear] |
| Guardrails | runtm-api guardrails limits|allowlist get|set, can-deploy, deploy-limits, cleanup --yes |
| Integrations | runtm-api integrations anthropic|openai get|set|delete|resolved [--org-scope] |
| Skills / MCP / Tools | runtm-api skills|mcp|tools create|get|list|update|delete; attach skills/MCP to templates with skills|mcp attach|detach|attachments <id> --template <tmpl_id> (see runtm-integrations) |
| Agents (Slack/GitHub) | runtm-api agents create|list|get|update|delete --type slack|github (see runtm-agents) |
| Auth | runtm-api auth status |
Endpoint Strategy
Everything hits the canonical Cloud API (/api/... on app.runtm.com). Three deliberate v0 fallbacks remain because they're built specifically for fire-and-forget agent UX:
| Command | Path | Why |
|---|
session launch | POST /api/v0/sessions/launch | Documented entry point for webhook / agent workflows; one call creates + prompts. |
session status | GET /api/v0/sessions/{id} | v0 returns last_prompt polling envelope for fire-and-forget. |
session prompt | POST /api/v0/sessions/{id}/prompt | Synchronous SSE stream; canonical equivalent splits into POST 202 + GET events (worse CLI UX). |
The CLI does not call OSS-only routes like /api/v0/deployments (that's the pip CLI's territory).
Prerequisites
Install the pre-built binary (macOS / Linux × amd64 / arm64, no Go required):
curl -fsSL https://runtm.com/install | bash
export RUNTM_API_KEY=runtm_sk_live_...
The installer drops runtm-api in /usr/local/bin (override with RUNTM_INSTALL_DIR=$HOME/.local/bin) and auto-installs these skill files into ~/.claude/skills/runtm/ and ~/.cursor/skills/runtm/ when those directories exist.
If you already have Go 1.23+ and prefer to compile from source:
go install github.com/runtm-ai/runtm/packages/agent/cmd/runtm-api@latest
runtm-api skills install
Org context for org-scoped operations (templates, team telemetry, team secrets, org instructions, guardrails) is auto-discovered from the API key, so org keys "just work" with no extra setup. Only set this when using a personal key against an org you belong to, or when switching between orgs:
export RUNTM_ORG_ID=org_abc123
runtm-api template list --org org_abc123
Required Input Resolution
- Check context first (prior output, conversation, env vars).
- If a value is missing, run the matching
list / get first:
- Session ID:
runtm-api session list
- Template ID:
runtm-api template list
- If still ambiguous, ask the user.
- Never run a command with an unresolved placeholder like
<id> or <org>.
Auth
runtm-api auth status
If authenticated: false, ask the user to set RUNTM_API_KEY (or run runtm-api login in the pip CLI). API keys are managed at https://app.runtm.com > Settings > API Keys.
Output
- All commands emit JSON to stdout. Parse it directly.
- Errors go to stderr as JSON:
{"error": "...", "status": 401, "hint": "..."}.
- Exit codes:
0 success, 1 API error, 2 auth error, 3 usage error.
- SSE commands (
session prompt, session events, session deploy run, template build-logs) stream JSON lines: {"event": "<type>", "data": <payload>}. Stream ends with event: "done".
Error Recovery
| Status | Cause | Fix |
|---|
| 401 | API key invalid or missing | RUNTM_API_KEY or rotate in dashboard |
| 403 | Missing scope or wrong org | runtm-api auth status to inspect; key may need templates:write, secrets:write, guardrails:write, etc. |
| 404 | Wrong ID | Run the matching list command first |
| 409 | Conflict (e.g. duplicate name) | Use a different name / --name flag |
| 422 | Body validation failed | Check the canonical endpoint schema at https://docs.runtm.com/cloud-api |
| 429 | Rate limited | Back off (5-10s) and retry |
| 5xx | Sandbox / upstream | Retry once; check https://status.runtm.com |
Scope Reference
| Operation | Required scope(s) |
|---|
session list|get|status|history|workspace-state|collaborators | sessions:read |
session create|destroy|rename|pause|resume|git|visibility|heartbeat|run-server | sessions:write (sessions:delete for destroy) |
session launch | sessions:write + sessions:prompt |
session connect|exec | sessions:terminal |
session prompt|prompt-cancel|events | sessions:prompt |
session prompt-rewind | sessions:write |
session file read|list|search | sessions:read |
session file write|delete|rename|mkdir | sessions:write |
session env get|detected | secrets:read |
session env set|delete|detect | secrets:write |
session instructions get | context:read |
session instructions set | context:write |
session deploy info | deployments:read |
session deploy scaffold|validate|preflight|run | deployments:write |
template list|get|repos|build-logs|build-logs-history | templates:read |
template create|update|fix-session|save-snapshot | templates:write |
template build | templates:build |
template delete | templates:delete |
template secrets list | secrets:read |
template secrets set|delete | secrets:write |
activity * | activity:read |
secrets list|resolved | secrets:read |
secrets set|delete | secrets:write (team needs admin/owner role) |
instructions get | context:read |
instructions set | context:write (org needs admin/owner role) |
guardrails limits|allowlist get | guardrails:read |
guardrails limits|allowlist set | guardrails:write (admin/owner) |
guardrails can-deploy|deploy-limits | deployments:read |
guardrails cleanup | guardrails:write (admin/owner) |
integrations * get|resolved | integrations:read |
integrations * set|delete | integrations:write (org needs admin/owner) |
More Skills
runtm-sessions -- session workflow recipes (launch, iterate, deploy, debug).runtm-templates -- full template lifecycle (create, build, fix, snapshot).runtm-debug -- inspect a session's state when something is wrong.runtm-integrations -- add/connect an integration (research API/SDK/CLI/MCP/repos/skills → weigh auth methods → user picks → build definition → connect in the UI); CRUD skills, MCP servers, and tools.runtm-agents -- create, list, and edit Slack/GitHub integration agents.
Subcommand Discovery
runtm-api --help
runtm-api <area> --help
runtm-api session deploy --help
runtm-api template fix-session --help
