runtm
CLI for Runtm – sandboxes where AI agents build and deploy.
Website: runtm.com · Docs: docs.runtm.com · Sign up: app.runtm.com
Installation
Recommended (uv):
uv tool install runtm
Alternative (pipx):
pipx install runtm
From PyPI (pip):
pip install runtm
With Sandbox Support
To use local sandboxes with AI agents:
pip install runtm[sandbox]
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. Start a sandbox and build with AI
runtm start
runtm prompt "Build a REST API with SQLite"
# 3. Deploy to a live URL
runtm deploy
You get a live HTTPS endpoint. Machines auto-stop when idle and wake on traffic.
Commands
Sandbox Commands
| Command | Description |
|---|---|
runtm start |
Start a sandbox session (interactive menu) |
runtm prompt "..." |
Send a prompt to the agent (autopilot mode) |
runtm attach [id] |
Attach to a sandbox (defaults to active) |
runtm session list |
List all sandbox sessions |
runtm session stop <id> |
Stop a session (preserves workspace) |
runtm session destroy <id> |
Destroy a session and delete workspace |
runtm session deploy |
Deploy from sandbox to live URL |
Project Commands
| Command | Description |
|---|---|
runtm init [template] |
Initialize from template (backend-service, web-app, static-site) |
runtm run |
Run project locally (auto-detects runtime) |
runtm validate |
Validate project before deployment |
runtm fix |
Auto-fix common issues (lockfiles) |
runtm deploy [path] |
Deploy project to a live URL |
Deployment Commands
| Command | Description |
|---|---|
runtm status <id> |
Show deployment status |
runtm logs <id> |
Show logs (build, deploy, runtime) |
runtm list |
List all deployments |
runtm search <query> |
Search deployments by description/tags |
runtm destroy <id> |
Destroy a deployment |
Configuration Commands
| Command | Description |
|---|---|
runtm config set/get/list |
Manage CLI configuration |
runtm secrets set/get/list/unset |
Manage environment secrets |
runtm domain add/status/remove |
Manage custom domains |
runtm approve |
Apply agent-proposed changes |
Authentication Commands
| Command | Description |
|---|---|
runtm login |
Authenticate with Runtm API |
runtm logout |
Remove saved credentials |
runtm doctor |
Check CLI setup and diagnose issues |
runtm version |
Show CLI version |
Sandbox Sessions
Start isolated environments where AI agents can build software:
# Start with interactive menu
runtm start
# Or go directly to autopilot mode
runtm start --autopilot
# Send prompts to the agent
runtm prompt "Build a todo API with SQLite"
runtm prompt --continue "Add authentication"
# Attach to see what's happening
runtm attach
# List all sessions
runtm session list
Modes
- Autopilot: Agent runs autonomously, control via
runtm prompt - Interactive: Drop into sandbox shell, control agent manually
Available Agents
claude-code- Anthropic's Claude Code (recommended)codex- OpenAI's Codex CLIgemini- Google's Gemini CLI
Authentication
Get your free API key at app.runtm.com. The CLI will prompt you to authenticate on first use.
# Manual login
runtm login
# Login with token directly
runtm login --token runtm_sk_xxx
# Check auth status
runtm doctor
# Logout
runtm logout
Token storage:
- Primary:
~/.runtm/credentialsfile (0o600 permissions) - Optional: System keychain (if
keyringpackage installed)
Environment variable override:
export RUNTM_API_KEY=runtm_sk_xxx # Overrides stored token
Configuration
# 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)RUNTM_DEBUG- Enable debug logging
Secrets Management
Manage environment variables for deployments:
# Set secrets
runtm secrets set DATABASE_URL=postgres://...
runtm secrets set API_KEY=sk-xxx
# List secrets
runtm secrets list
# Get a secret value
runtm secrets get DATABASE_URL
# Remove a secret
runtm secrets unset OLD_KEY
Secrets are stored in .env.local (gitignored) and injected at deploy time.
Troubleshooting
# Check CLI setup and diagnose issues
runtm doctor
Example output:
runtm v0.2.7
API URL: https://app.runtm.com/api
Auth storage: keychain (api_token@app.runtm.com)
Auth status: ✓ Authenticated as user@example.com
Connectivity: ✓ API reachable (142ms)
Ready to deploy! Run: runtm init
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.
Deployment
# 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
Redeployment (CI/CD)
Runtm supports automatic redeployment based on the project name in runtm.yaml:
# 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
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
Development
# Install in editable mode with sandbox support
pip install -e ".[dev,sandbox]"
pip install -e ../sandbox
pip install -e ../agents
# Use the development CLI (avoids conflicts with PyPI version)
runtm-dev start # Start sandbox session
runtm-dev prompt "Build an API" # Send prompt to agent
runtm-dev session list # List sessions
# 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
runtm vs runtm-dev
| CLI | Source | Use Case |
|---|---|---|
runtm |
PyPI (pip install runtm) |
Production use |
runtm-dev |
Local .venv/ |
Development (includes sandbox/agents) |
If you have the PyPI version installed globally, use runtm-dev to ensure you're running your local development code with full sandbox support.
1 maintainer
Release files for runtm 0.2.156
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| runtm-0.2.156.tar.gz | 143.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| runtm-0.2.156-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 231.7 kB
Release files / runtm-0.2.156.tar.gz
| Download URL | runtm-0.2.156.tar.gz |
|---|---|
| Size | 143.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aac582b52ce669be6d398587462ba6c40766802e05738fb68096479d123d3733
|
|
BLAKE2b-256 checksum How to use checksums |
6865b09e95b6961c76beb9a289a7ec32190d278c633cff2e8cf90ada8e29833c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / runtm-0.2.156-py3-none-any.whl
| Download URL | runtm-0.2.156-py3-none-any.whl |
|---|---|
| Size | 87.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a93a94bf5398d8694e79622a37f0b7a59228141f9a054a1b24d1aaa5bec8378
|
|
BLAKE2b-256 checksum How to use checksums |
efbc251f703843be1b619e63c3fe36466c1a6d95a4b44a38aa3fac7ede43e778
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
