runtm 0.2.2

The runtime + control plane for agent-built software: create, run, deploy, observe, reuse and destroy apps

runtm

runtm is the runtime + control plane for agent-built software: create, run, deploy, observe, reuse and destroy apps with guardrails and speed.

Deploy AI-generated code to live URLs in minutes.

🌐 Website: runtm.com · Try it free: app.runtm.com

Installation

Recommended (uv):

uv tool install runtm

Alternative (pipx):

pipx install runtm

From PyPI (pip):

pip install runtm

Upgrading

# Upgrade to latest version (uv)
uv tool upgrade runtm

# Or force reinstall
uv tool install runtm --force

# With pipx
pipx upgrade runtm

# With pip
pip install --upgrade runtm

Quick Start

# 1. Authenticate with Runtm
runtm login

# 2. Initialize a new project
runtm init backend-service

# 3. Deploy to a live URL
runtm deploy

Commands

Command	Description
runtm login	Authenticate with Runtm API
runtm logout	Remove saved credentials
runtm doctor	Check CLI setup and diagnose issues
runtm init <template>	Scaffold from template
runtm run	Run project locally (auto-detects runtime)
runtm validate	Validate project before deployment
runtm deploy [path]	Deploy project to a live URL
runtm status <id>	Show deployment status
runtm logs <id>	Show logs (build, deploy, runtime)
runtm list	List all deployments
runtm destroy <id>	Destroy a deployment
runtm config set/get/list	Manage CLI configuration

Authentication

Get your free API key at app.runtm.com and authenticate:

# Login (prompts for API key)
runtm login

# Login with token directly
runtm login --token runtm_sk_xxx

# Login without validation (self-hosted/offline)
runtm login --no-verify

# Check auth status
runtm doctor

# Logout
runtm logout

Token storage:

• macOS: Keychain
• Windows: Credential Locker
• Linux: Secret Service (or ~/.runtm/credentials with 0o600 permissions)

Environment variable override:

export RUNTM_API_KEY=runtm_sk_xxx  # Overrides stored token

Configuration

Manage CLI settings with the config command:

# Set API URL (for self-hosting)
runtm config set api_url=https://self-hosted.example.com/api

# Get a config value
runtm config get api_url

# List all config values
runtm config list

# Reset to defaults
runtm config reset

Config file: ~/.runtm/config.yaml

Environment variables:

• RUNTM_API_URL - API endpoint (overrides config)
• RUNTM_API_KEY - API key (overrides stored token)

Troubleshooting

# Check CLI setup and diagnose issues
runtm doctor

Example output:

runtm v0.1.0
  API URL:      https://app.runtm.com/api
  Auth storage: keychain ([e-mail])
  Auth status:  ✓ Authenticated as [e-mail]
  Connectivity: ✓ API reachable (142ms)
  
  Ready to deploy! Run: runtm init backend-service

Machine Tiers

All deployments use auto-stop for cost savings (machines stop when idle and start automatically on traffic).

Tier	CPUs	Memory	Est. Cost	Use Case
starter (default)	1 shared	256MB	~$2/month*	Simple tools, APIs
standard	1 shared	512MB	~$5/month*	Most workloads
performance	2 shared	1GB	~$10/month*	Full-stack apps

*Costs are estimates for 24/7 operation. With auto-stop, costs are much lower for low-traffic services.

Usage

# Initialize a new backend service project
runtm init backend-service

# Run locally (auto-detects runtime and port)
runtm run

# Validate before deploying
runtm validate

# Deploy to a live URL (uses starter tier by default)
runtm deploy

# Deploy with a specific tier
runtm deploy --tier standard
runtm deploy --tier performance

# Check deployment status
runtm status dep_abc123

# View logs
runtm logs dep_abc123

Setting Machine Tier

You can specify the machine tier in two ways:

1. Via CLI flag (overrides manifest):

   runtm deploy --tier standard
   runtm deploy --tier performance
   

2. In runtm.yaml (persistent setting):

   name: my-service
   template: backend-service
   runtime: python
   tier: standard  # Options: starter, standard, performance
   

Redeployment (CI/CD)

Runtm supports automatic redeployment based on the project name in runtm.yaml. When you deploy a project with the same name as an existing deployment:

• The existing infrastructure is updated (same URL)
• A new version is created
• The previous version is marked as not latest

# First deploy - creates new deployment
runtm deploy                   # → v1, creates new URL

# Fix a bug, then redeploy - updates existing
runtm deploy                   # → v2, same URL, updated code

# Force a completely new deployment
runtm deploy --new             # → v1, new deployment, new URL

This enables CI/CD workflows where an agent or user can:

1. Build code
2. Deploy with runtm deploy
3. Find and fix bugs
4. Redeploy with runtm deploy (same command, updates in place)

Logs

The logs command provides comprehensive access to build, deploy, and runtime logs.

# All logs (build + deploy + recent runtime)
runtm logs dep_abc123

# Filter by log type
runtm logs dep_abc123 --type runtime
runtm logs dep_abc123 --type build

# More runtime log lines
runtm logs dep_abc123 --lines 100

# Search logs
runtm logs dep_abc123 --search "error"
runtm logs dep_abc123 --search "error,warning,timeout"  # OR logic

# Pipe to grep (Heroku-style)
runtm logs dep_abc123 --raw | grep "error"

# JSON output for AI agents
runtm logs dep_abc123 --json

Log Options

Option	Short	Description
--type TYPE	-t	Filter: build, deploy, runtime
--lines N	-n	Runtime log lines (default: 20)
--search TEXT	-s	Filter by text, comma-separated, or regex
--json		JSON output for programmatic access
--raw		Raw output for piping to grep/awk

Development

# Install in editable mode
pip install -e ".[dev]"

# Configure CLI to use local API (add to ~/.zshrc or ~/.bashrc)
export RUNTM_API_URL=http://localhost:8000
export RUNTM_API_KEY=dev-token-change-in-production

# Run tests
pytest