Runtm

The core of Runtime is open source, allowing teams to run the platform on their own infrastructure. Key capabilities include:

• Self-Hosting: Run the full Runtime stack on your own infrastructure using Docker Compose.
• CLI Management: Use the CLI to manage sandboxes, deployments, secrets, and domains locally.
• OSS Deployment API: Programmatically access deployments, logs, and domains via the open-source deployment API.

Note: Most users should refer to the hosted platform documentation or the Cloud API Reference. These open-source guides are specifically for teams self-hosting or contributing to the project.

The Backend Service Template is a FastAPI-based Python template designed for Runtm. It is intended for API-first services that require Python compute, such as scrapers, crawlers, agent backends with tool calls, webhooks, and data processing integrations.

Stack:

• FastAPI: High-performance API framework
• Pydantic: Data validation and serialization
• Uvicorn: ASGI server
• Pytest: Testing framework

The web-app template is a fullstack architecture designed for interactive applications, dashboards, and SaaS products.

Technical Stack:

• Frontend: Next.js 14 (App Router)
• Backend: Python FastAPI
• Port: 3000 (The frontend proxies requests to the backend)
• Health Endpoint: /health

⚠️ Critical Resource Requirement: This template requires at least the standard tier (minimum 512MB RAM) because it runs both Node.js and Python processes simultaneously. The starter tier (256MB) is insufficient.

Runtm (Runtime) Cloud is a platform for creating and running AI agents equipped with jobs, success metrics, tools, runbooks, triggers, and guardrails.

To interact with the cloud, use the runtm-api binary. Note that the pip runtm CLI is intended for local development only and does not interact with the hosted API.

Accessing Documentation via CLI: If you do not have a fetch tool, you can access documentation directly through the CLI:

• runtm-api docs: Prints the llms.txt index.
• runtm-api docs <path>: Prints a specific documentation page (e.g., runtm-api docs build/give-it-tools).

The backend-service template follows a structured layout for FastAPI applications:

• runtm.yaml: Deployment manifest.
• runtm.discovery.yaml: Search metadata.
• Dockerfile: Container build instructions.
• pyproject.toml: Python dependencies.
• app/main.py: FastAPI entry point.
• app/api/v1/: API route definitions (e.g., health.py, routes.py).
• app/services/: Business logic (e.g., processor.py).
• app/core/: Core settings and logging (config.py, logging.py).
• app/db/: Database layer including models, sessions, and migrations.
• tests/: Test suite.

Runtime offers two primary deployment models:

• Runtime Cloud: The fully managed platform at app.runtm.com. This includes hosting for agents, templates, triggers, guardrails, grading, and the scorecard.
• Open Source (Self-hosted): The open-source components available at github.com/runtm-ai/runtm. This covers the runtm CLI, the deployment API, and the templates used to produce agent applications.

A session is an isolated cloud sandbox where coding agents (such as Claude Code, Codex, or Cursor CLI) execute commands, edit files, and provide live preview URLs. The Cloud API allows you to manage the full lifecycle of these sessions, including listing, creating, retrieving, and destroying them.

Required Scopes

Depending on the operation, you need one of the following scopes:

• sessions:read: Required for listing and getting sessions.
• sessions:write: Required for creating sessions.
• sessions:delete: Required for destroying sessions.

Authentication & Organization Context

• All session endpoints honor the X-Organization-Id header.
• Personal keys: May omit the header to operate on personal sessions (organization_id = NULL).
• Organization keys: Must include the X-Organization-Id header that matches the key's organization.

The open-source version of Runtime provides several specialized guides and features:

Guides

• Agent Workflow: Learn how agents propose changes and how humans approve them.
• Discovery: Learn how to make your deployments searchable and discoverable.
• Logs & Debugging: Instructions for diagnosing issues with build and runtime logs.
• Troubleshooting: Solutions for common problems.

Features

• Machine Tiers: Manage compute sizes and suspended-state behavior.
• Secrets: Manage environment variables for your deployments.
• Database: Utilize persistent SQLite storage for deployed applications.
• Custom Domains: Connect your own domains with automatic SSL.
• Authentication: Add authentication layers to your deployed applications.

A Skill is a reusable bundle that teaches an agent how to perform specific workflows. It serves as the primary unit of agent extension. When a skill is attached to a session or a template, it provides the agent with authoritative guidance, reference materials, and specialized tools.

A skill bundle consists of four components:

1. Entry markdown (SKILL.md): The primary instruction document the agent reads.
2. Files: Reference materials like code samples, schemas, diagrams, or configuration templates mounted into the sandbox.
3. MCP servers: Configured Model Context Protocol tools (via stdio, http, or sse) that the agent can call.
4. Required tooling: System or language packages (resolved via mise) installed in the sandbox at template build time.