runtm

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

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

Org templates (full lifecycle)

Activity (telemetry)

Secrets / Instructions / Guardrails / Providers / Plan

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:

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_...   # from https://app.runtm.com > Settings > API Keys

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   # optional; usually only personal keys need this
# or pass per command:
runtm-api template list --org org_abc123

Required Input Resolution

1. Check context first (prior output, conversation, env vars).
2. If a value is missing, run the matching list / get first:
   • Session ID: runtm-api session list
   • Template ID: runtm-api template list
3. If still ambiguous, ask the user.
4. Never run a command with an unresolved placeholder like <id> or <org>.

Auth

runtm-api auth status   # returns authenticated, scopes, org, tenant

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

Scope Reference

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 external 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. NB: "integration" means external tooling; LLM provider keys (Anthropic/OpenAI) live under runtm-api providers.
• runtm-agents -- create, list, and edit Slack/GitHub integration agents.

Subcommand Discovery

runtm-api --help
runtm-api <area> --help            # session, template, activity, secrets, instructions, guardrails, integrations, auth
runtm-api session deploy --help    # nested subcommand trees
runtm-api template fix-session --help