### Manual Local Setup: Backend (FastAPI)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/README.md

Guides users through manually starting the FastAPI backend server, including installing dependencies and running Uvicorn.

```bash
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload --port 8080
```

--------------------------------

### Manual Local Setup: Frontend (Next.js)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/README.md

Details the steps to start the Next.js development server, including installing npm dependencies and running the dev script.

```bash
cd frontend
npm install
npm run dev
```

--------------------------------

### Runtm Quick Start

Source: https://github.com/runtm-ai/runtm/blob/main/packages/cli/README.md

A quick start guide for using the Runtm CLI, covering authentication, starting a sandbox, building with AI, and deploying to a live URL.

```bash
# 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
```

--------------------------------

### Runtm API Development Setup

Source: https://github.com/runtm-ai/runtm/blob/main/packages/api/README.md

This section provides essential commands for setting up and running the Runtm API during development. It covers installing dependencies, applying database migrations, starting the development server with hot-reloading, and running automated tests.

```bash
# Install dependencies
pip install -e ".[dev]"

# Run migrations
alembic upgrade head

# Start server
uvicorn runtm_api.main:app --reload --host 0.0.0.0 --port 8000

# Run tests
pytest
```

--------------------------------

### Self-Hosting Runtm Setup (Bash)

Source: https://context7.com/runtm-ai/runtm/llms.txt

Provides bash commands for setting up a self-hosted Runtm instance. This includes cloning the repository, configuring environment variables, installing dependencies, starting local services with Docker Compose, and using the development CLI.

```bash
# Clone repository
git clone https://github.com/runtm-ai/runtm.git
cd runtm

# Copy environment configuration
cp infra/local.env.example .env

# Install packages (includes sandbox and agents)
./scripts/dev.sh setup

# Start local services
docker compose -f infra/docker-compose.yml up -d

# Use development CLI (includes sandbox/agents packages)
runtm-dev start                    # Start a sandbox session
runtm-dev prompt "Build an API"    # Send prompt to agent

# Configure CLI for self-hosted instance
runtm config set api_url=https://self-hosted.example.com/api
```

--------------------------------

### Troubleshoot Runtm CLI Installation

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Re-installs the Runtm CLI, forcing the installation to ensure it's correctly added to your PATH.

```bash
uv tool install runtm --force
```

--------------------------------

### Test Runtm Application Locally

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Starts the development server for your Runtm application. The CLI automatically detects and starts the appropriate dev server.

```bash
runtm run
```

--------------------------------

### Deploy Runtm Application

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Deploys your Runtm application. The first deployment may take 2-3 minutes, while subsequent deployments are faster.

```bash
runtm deploy
```

--------------------------------

### Clone and Start Runtm with Docker Compose

Source: https://github.com/runtm-ai/runtm/blob/main/docs/self-hosting/docker-compose.mdx

This snippet outlines the initial steps to clone the Runtm repository, set up the local environment file, and start all services using a development script. It assumes basic familiarity with Git and the command line.

```bash
# Clone repository
git clone https://github.com/runtm-ai/runtm.git
cd runtm

# Copy environment template
cp infra/local.env.example .env

# Edit .env and add your FLY_API_TOKEN
vim .env

# Start services
./scripts/dev.sh up
```

--------------------------------

### Initialize a New Runtm Project

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Creates an isolated workspace for your agent. You will be prompted to authenticate if you haven't already.

```bash
runtm init
```

--------------------------------

### Initialize and Deploy with Runtm CLI

Source: https://github.com/runtm-ai/runtm/blob/main/docs/introduction.mdx

These commands are used to initialize a new sandbox environment and deploy the built software using the Runtm command-line interface. They are fundamental for getting started with Runtm.

```bash
runtm init
runtm deploy
```

--------------------------------

### Local Development Commands (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/static-site/README.md

Commands to install dependencies, start the development server, build for production, lint, and format code using npm.

```bash
# Recommended: Use runtm run (auto-detects runtime and port)
runtm run

# Or manually:
npm install
npm run dev
```

```bash
npm run build    # Build for production
npm run lint     # Lint code
npm run format   # Format code
```

--------------------------------

### Troubleshoot Runtm Lockfile Errors

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Automatically fixes issues related to lockfiles during deployment by accepting default options.

```bash
runtm deploy --yes
```

--------------------------------

### Install Runtm CLI

Source: https://github.com/runtm-ai/runtm/blob/main/docs/introduction.mdx

This command installs the Runtm command-line interface tool using the 'uv tool install' command. Ensure you have 'uv' installed and configured in your environment.

```bash
uv tool install runtm
```

--------------------------------

### Build Go Application with Docker

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/CLAUDE.md

Example Dockerfile for building a Go application using a multi-stage build. It compiles the Go binary in a builder stage and then copies the executable to a minimal Alpine base image. The Dockerfile exposes port 8080 and sets the command to run the compiled binary.

```dockerfile
# Example: Go
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o main .

FROM alpine:latest
COPY --from=builder /app/main /main
EXPOSE 8080
CMD ["/main"]
```

--------------------------------

### Runtm Self-Hosting Quick Start (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/self-hosting/overview.mdx

Bash script to clone the Runtm repository, set up local environment variables, and start the Runtm services using Docker Compose.

```bash
git clone https://github.com/runtm-ai/runtm.git
cd runtm

cp infra/local.env.example .env
# Edit .env with your provider credentials

docker compose -f infra/docker-compose.yml up -d
```

--------------------------------

### Verify Runtm Setup

Source: https://github.com/runtm-ai/runtm/blob/main/docs/self-hosting/requirements.mdx

Commands to verify that essential tools like Docker are installed and running, and to check system resource availability (disk space, memory). These checks ensure the environment is ready for Runtm deployment.

```bash
# Check Docker
docker --version
docker compose version

# Check Docker is running
docker info

# Check disk space
df -h

# Check memory
free -h  # Linux
vm_stat  # macOS
```

--------------------------------

### Run Runtm Application Locally

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/AGENT.md

Commands to start the Runtm application locally. The `runtm run` command is recommended for starting both frontend and backend, utilizing Bun if available for faster performance. Alternatively, backend and frontend can be started manually in separate terminals.

```bash
# Recommended: starts both frontend and backend
# Uses Bun if available (3x faster), falls back to npm
runtm run

# Backend: http://localhost:8080
# Frontend: http://localhost:3000

```

```bash
# Terminal 1: Backend
cd backend && pip install -e ".[dev]" && uvicorn app.main:app --reload --port 8080

# Terminal 2: Frontend (Bun preferred for speed)
cd frontend && bun install && bun run dev
# Or with npm:
cd frontend && npm install && npm run dev

```

--------------------------------

### Check Runtm CLI Setup

Source: https://github.com/runtm-ai/runtm/blob/main/packages/cli/README.md

Diagnose potential issues with your Runtm CLI installation and configuration. This command verifies API connectivity, authentication status, and provides guidance for next steps.

```bash
# Check CLI setup and diagnose issues
runtm doctor
```

--------------------------------

### Troubleshooting: Manual Dependency Installation

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/run.mdx

Shows manual commands for installing dependencies for Python (pip) and Node.js (bun or npm) projects, useful when automatic installation fails.

```bash
# Python
pip install -e .

# Node.js
bun install  # or npm install
```

--------------------------------

### Install Runtm CLI

Source: https://github.com/runtm-ai/runtm/blob/main/packages/cli/README.md

Installs the Runtm CLI using different package managers. The recommended method is 'uv'. An alternative for local sandbox support is to install with the 'sandbox' extra.

```bash
uv tool install runtm

pipx install runtm

pip install runtm

pip install runtm[sandbox]
```

--------------------------------

### Install Runtm CLI

Source: https://context7.com/runtm-ai/runtm/llms.txt

Instructions for installing the Runtm CLI using different package managers like uv, pipx, and pip. It also includes commands to verify the installation and upgrade to the latest version.

```bash
# Install via uv (recommended)
uv tool install runtm

# Alternative: pipx
pipx install runtm

# Alternative: pip
pip install runtm

# Verify installation
runtm version

# Upgrade to latest
uv tool upgrade runtm
```

--------------------------------

### Dockerfile Example for Elixir Application

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/README.md

A multi-stage Dockerfile for building an Elixir application using Mix and Hex. It compiles the release in a builder stage and then copies the release artifacts to a minimal Alpine Linux image. The Dockerfile exposes port 8080 and starts the application using the generated script.

```dockerfile
FROM elixir:1.15-alpine AS builder
ENV MIX_ENV=prod
WORKDIR /app
COPY . .
RUN mix deps.get && mix release

FROM alpine:latest
COPY --from=builder /app/_build/prod/rel/myapp ./
EXPOSE 8080
CMD ["bin/myapp", "start"]
```

--------------------------------

### Install Runtm CLI

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/overview.mdx

Instructions for installing the Runtm CLI using different package managers. Ensure you have the chosen package manager installed before proceeding.

```bash
uv tool install runtm
```

```bash
pipx install runtm
```

```bash
pip install runtm
```

--------------------------------

### Replace Dockerfile Example (Go)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/AGENT.md

This Dockerfile example demonstrates how to build a Go application for deployment. It uses a multi-stage build with a Go builder image and a lean Alpine image for the final artifact. Ensure the exposed port matches the runtm.yaml configuration.

```dockerfile
# Example: Go application
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o main .

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]
```

--------------------------------

### Initialize and Run Static Site Template

Source: https://github.com/runtm-ai/runtm/blob/main/docs/templates/static-site.mdx

Command-line instructions to initialize the static-site template using runtm, navigate to the project directory, and start the development server.

```bash
runtm init static-site
cd static-site
runtm run
```

--------------------------------

### Initialize and Run backend-service Template

Source: https://github.com/runtm-ai/runtm/blob/main/docs/templates/backend-service.mdx

Demonstrates how to initialize the backend-service template using the runtm CLI, navigate to the project directory, and start the development server. It also points to the OpenAPI documentation URL.

```bash
runtm init backend-service
cd backend-service
runtm run
```

--------------------------------

### Get Deployment Details (JavaScript)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/deployments/get.mdx

Example of how to retrieve deployment status and details using JavaScript's fetch API. This code makes a GET request and logs the deployment state and URL if present.

```javascript
const response = await fetch(
  "https://app.runtm.com/api/v0/deployments/dep_abc123xyz",
  {
    headers: {
      "Authorization": "Bearer runtm_xxx"
    }
  }
);

const data = await response.json();
console.log(`Status: ${data.state}`);
if (data.url) {
  console.log(`URL: ${data.url}`);
}
```

--------------------------------

### Get Deployment Details (Python)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/deployments/get.mdx

Example of how to retrieve deployment status and details using Python's requests library. This script sends a GET request and prints the deployment state and URL if available.

```python
import requests

response = requests.get(
    "https://app.runtm.com/api/v0/deployments/dep_abc123xyz",
    headers={"Authorization": "Bearer runtm_xxx"}
)

data = response.json()
print(f"Status: {data['state']}")
if data["url"]:
    print(f"URL: {data['url']}")
```

--------------------------------

### Initialize and Run web-app Template

Source: https://github.com/runtm-ai/runtm/blob/main/docs/templates/web-app.mdx

Quick start commands to initialize the web-app template, navigate into the project directory, and run the application. This sets up both the Next.js frontend and FastAPI backend.

```bash
runtm init web-app
cd web-app
runtm run
```

--------------------------------

### Start a Local Runtm Sandbox Session

Source: https://github.com/runtm-ai/runtm/blob/main/README.md

Initiates a local sandbox session for an AI agent to start coding. It can automatically install dependencies on the first run and supports starting with pre-defined templates or specific agents.

```bash
# Start a local sandbox session
runtm session start

# Start with a template
runtm session start --template web-app

# Use a different agent
runtm session start --agent codex
```

--------------------------------

### Run Frontend Linting with NPM

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/README.md

Demonstrates how to run the frontend linter using npm.

```bash
cd frontend
npm run lint
```

--------------------------------

### Get Runtm CLI Configuration Value

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/config.mdx

Retrieve a specific configuration value using the 'runtm config get' command followed by the key name. The output can be captured in shell variables for use in scripts. For example, to get the API URL, use 'runtm config get api_url'.

```bash
# Get API URL
runtm config get api_url

# Use in scripts
API_URL=$(runtm config get api_url)
```

--------------------------------

### Get Deployment Details (cURL)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/deployments/get.mdx

Example of how to retrieve deployment status and details using cURL. This command requires the deployment ID and an authorization token.

```bash
curl -X GET "https://app.runtm.com/api/v0/deployments/dep_abc123xyz" \
  -H "Authorization: Bearer runtm_xxx"
```

--------------------------------

### Get Deployment Logs (cURL)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/logs.mdx

Examples of fetching deployment logs using cURL. Demonstrates retrieving all logs, filtering by type, and searching for specific keywords or patterns. Requires an Authorization header.

```bash
# Get all logs
curl -X GET "https://app.runtm.com/api/v0/deployments/dep_abc123xyz/logs" \
  -H "Authorization: Bearer runtm_xxx"

# Get only build logs
curl -X GET "https://app.runtm.com/api/v0/deployments/dep_abc123xyz/logs?type=build" \
  -H "Authorization: Bearer runtm_xxx"

# Search for errors
curl -X GET "https://app.runtm.com/api/v0/deployments/dep_abc123xyz/logs?search=error,failed" \
  -H "Authorization: Bearer runtm_xxx"
```

--------------------------------

### Get Deployment Logs (JavaScript)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/logs.mdx

JavaScript example using the `fetch` API to retrieve deployment logs. Demonstrates constructing query parameters and setting the Authorization header. Iterates over the response logs to print their type and content to the console.

```javascript
const params = new URLSearchParams({
  type: "runtime",
  lines: "100",
  search: "error"
});

const response = await fetch(
  `https://app.runtm.com/api/v0/deployments/dep_abc123xyz/logs?${params}`,
  {
    headers: {
      "Authorization": "Bearer runtm_xxx"
    }
  }
);

const data = await response.json();
data.logs.forEach(log => {
  console.log(`[${log.log_type}] ${log.content}`);
});
```

--------------------------------

### Run Node.js Project Locally with runtm (npm)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/run.mdx

Runs a Node.js project locally using npm as the package manager and script runner if Bun is not available. Installs dependencies with 'npm install' and starts the development server with 'npm run dev'.

```bash
runtm run

# Equivalent commands without Bun:
npm install
npm run dev
```

--------------------------------

### Get Deployment Logs (Python)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/logs.mdx

Python example using the `requests` library to fetch deployment logs. Shows how to specify log type, number of lines, and search terms in the request parameters. Parses the JSON response to display log content.

```python
import requests

# Get runtime logs with search
response = requests.get(
    "https://app.runtm.com/api/v0/deployments/dep_abc123xyz/logs",
    headers={"Authorization": "Bearer runtm_xxx"},
    params={
        "type": "runtime",
        "lines": 100,
        "search": "error"
    }
)

data = response.json()
for log in data["logs"]:
    print(f"[{log['log_type']}] {log['content']}")
```

--------------------------------

### Activate Development Environment (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/CONTRIBUTING.md

Activates the Python virtual environment created during the setup process. This ensures that the development CLI and installed packages are accessible.

```bash
source .venv/bin/activate
```

--------------------------------

### Create Database Migrations (Bash & Alembic)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/backend-service/AGENT.md

Instructions for creating database migrations using Alembic. It covers generating a new migration script with autogenerate and notes that migrations run automatically on startup.

```bash
# Generate a migration
cd app/db && alembic revision --autogenerate -m "add items table"
```

--------------------------------

### Create Deployment with Idempotency Key (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/api/overview.mdx

Shows how to create a deployment using a POST request, including the 'Idempotency-Key' header for safe retries. This header ensures that duplicate requests do not result in unintended side effects, such as creating multiple identical deployments. It also includes the submission of a manifest and artifact.

```bash
curl -X POST "https://app.runtm.com/api/v0/deployments" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "Idempotency-Key: unique-request-id-123" \
  -F "manifest=@runtm.yaml" \
  -F "artifact=@artifact.zip"
```

--------------------------------

### View Runtm Application Logs

Source: https://github.com/runtm-ai/runtm/blob/main/docs/quickstart.mdx

Retrieves logs for a specific deployment ID. Logs can be filtered by type, such as 'build' or 'runtime', to aid in debugging.

```bash
runtm logs dep_abc123xyz
```

```bash
runtm logs dep_abc123xyz --type build
```

```bash
runtm logs dep_abc123xyz --type runtime
```

--------------------------------

### Dockerfile Example for Go Application

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/README.md

A multi-stage Dockerfile for building a Go application. It first compiles the Go code in a builder stage and then copies the executable to a lean Alpine Linux image. The Dockerfile exposes port 8080 and sets the command to run the compiled binary.

```dockerfile
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o main .

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/main .
EXPOSE 8080
CMD ["./main"]
```

--------------------------------

### Deploy Application with Runtm

Source: https://github.com/runtm-ai/runtm/blob/main/packages/cli/README.md

Deploy your application to a live URL using the Runtm CLI. Supports deploying to the default 'starter' tier or specifying other tiers like 'standard' or 'performance'.

```bash
# 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
```

--------------------------------

### Start Runtm Sandbox Session

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/session.mdx

Initiates a new sandbox session. Can be run interactively with a menu or directly in autopilot mode. Supports templates and specific agents for customized setups.

```bash
# Start a sandbox (interactive menu)
runtm start

# Or go directly to autopilot mode
runtm start --autopilot

# Skip to interactive mode
runtm start --interactive

# With a template
runtm start --template web-app

# With a specific agent
runtm start --agent claude-code
```

--------------------------------

### Python Service Logic Example

Source: https://github.com/runtm-ai/runtm/blob/main/templates/backend-service/AGENT.md

Demonstrates how to add business logic to a service class in Python. It includes initializing resources and defining a processing method that takes input data and returns a dictionary.

```python
# app/services/my_feature.py
class MyFeatureService:
    def __init__(self):
        # Initialize resources
        pass
    
    def process(self, input_data: str) -> dict:
        # Your business logic here
        return {"result": "processed"}

my_feature_service = MyFeatureService()
```

--------------------------------

### Write and Run Tests (Python & Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/backend-service/AGENT.md

Demonstrates how to write tests for the Runtm application using FastAPI's TestClient and run them with pytest. It includes an example test function and the command to execute tests.

```python
# tests/test_my_endpoint.py
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_my_endpoint():
    response = client.post("/api/v1/my-endpoint", json={"key": "value"})
    assert response.status_code == 200
```

```bash
pytest -q
```

--------------------------------

### Run Python Project Locally with runtm

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/run.mdx

Specifically runs a Python project locally. It installs dependencies using pip and starts the development server using uvicorn with hot reloading enabled.

```bash
runtm run

# Equivalent commands:
pip install -e . --quiet
uvicorn app.main:app --port 8080 --reload
```

--------------------------------

### Self-Host Runtm Development Environment

Source: https://github.com/runtm-ai/runtm/blob/main/README.md

Sets up and runs the Runtm development environment locally for self-hosting. This involves cloning the repository, configuring environment variables, installing dependencies, and starting Docker services.

```bash
git clone https://github.com/runtm-ai/runtm.git
cd runtm
cp infra/local.env.example .env

# Install packages (includes sandbox and agents)
./scripts/dev.sh setup

# Start local services
docker compose -f infra/docker-compose.yml up -d

# Use the development CLI
runtm-dev start                    # Start a sandbox session
runtm-dev prompt "Build an API"    # Send prompt to agent
```

--------------------------------

### Initialize a Runtm Project with a Template

Source: https://github.com/runtm-ai/runtm/blob/main/docs/templates/overview.mdx

This command initializes a new Runtm project using a specified template. It sets up the basic project structure and configuration files required for deployment. After initialization, you navigate into the project directory and deploy it.

```bash
runtm init backend-service
cd backend-service
runtm deploy
```

--------------------------------

### Get Session in Server Components with Runtm Auth

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/CLAUDE.md

This example demonstrates how to retrieve the current user's session information within server components using the `getSession` function from the Runtm authentication library.

```typescript
// Get session in server components
import { getSession } from "@/lib/auth";
const session = await getSession({ headers: headers() });
```

--------------------------------

### Runtm CLI Help Commands

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/overview.mdx

Examples of how to access help information for the Runtm CLI. Use `--help` for general assistance or on specific commands for detailed usage.

```bash
# General help
runtm --help
```

```bash
# Command-specific help
runtm deploy --help
runtm logs --help
```

--------------------------------

### SQLAlchemy Database Model and Endpoint Example

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/CLAUDE.md

This Python code snippet illustrates how to define a SQLAlchemy model for a 'users' table and create a FastAPI endpoint to retrieve all users. It utilizes `fastapi.Depends` to get a database session.

```python
from fastapi import Depends
from sqlalchemy.orm import Session
from app.db import Base, get_db

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True)

@router.get("/users")
def get_users(db: Session = Depends(get_db)):
    return db.query(User).all()
```

--------------------------------

### Configure Discovery Metadata with runtm.discovery.yaml

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/AGENT.md

This snippet shows an example of a correctly configured `runtm.discovery.yaml` file. It includes fields for description, summary, capabilities, use cases, and tags, which are crucial for making your application discoverable in the dashboard. Ensure all `# TODO:` placeholders are replaced with actual content before deployment.

```yaml
description: |
  A high-performance Go API for processing webhook events from payment
  providers. Handles authentication, rate limiting, and async job processing.

summary: "Go webhook processor with async job queue"

capabilities:
  - "Process webhook events from Stripe, PayPal"
  - "Async job processing with retry logic"
  - "Rate limiting and authentication"

use_cases:
  - "E-commerce platforms needing payment webhooks"
  - "Event-driven architectures"

tags:
  - go
  - api
  - webhooks
  - payments

```

--------------------------------

### Next.js Page Component Structure

Source: https://github.com/runtm-ai/runtm/blob/main/templates/static-site/CLAUDE.md

Example of creating a new page component in Next.js, including importing layout and page-specific components. This structure helps organize page-specific logic and reusable UI elements.

```tsx
// app/pricing/page.tsx
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';
import { PricingHero, PricingPlans } from '@/components/pages/pricing';

export default function PricingPage() {
  return (
    <div className="flex min-h-screen flex-col">
      <Header />
      <main className="flex-1">
        <PricingHero />
        <PricingPlans />
      </main>
      <Footer />
    </div>
  );
}
```

--------------------------------

### Run Node.js Project Locally with runtm (Bun)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/cli/run.mdx

Runs a Node.js project locally, prioritizing Bun for faster dependency installation and script execution if available. Starts the development server using 'bun run dev'.

```bash
runtm run

# Equivalent commands with Bun:
bun install
bun run dev
```

--------------------------------

### Python Example: Create, Attach, and Destroy a Sandbox

Source: https://github.com/runtm-ai/runtm/blob/main/packages/sandbox/README.md

This Python code demonstrates how to use the LocalSandboxProvider to create, attach to, and destroy an isolated sandbox environment. It requires the runtm-sandbox library and its dependencies.

```python
from runtm_sandbox import LocalSandboxProvider
from runtm_shared.types import SandboxConfig

provider = LocalSandboxProvider()

# Create a sandbox
sandbox = provider.create("sbx_123", SandboxConfig())

# Attach to sandbox (runs isolated shell)
exit_code = provider.attach("sbx_123")

# Clean up
provider.destroy("sbx_123")
```

--------------------------------

### Request New Environment Variables in runtm.requests.yaml

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/CLAUDE.md

Example of a `runtm.requests.yaml` file used to propose new environment variables. It specifies a variable 'API_KEY' as a secret and provides a reason for its necessity. This file is used in conjunction with `runtm approve`.

```yaml
requested:
  env_vars:
    - name: API_KEY
      secret: true
      reason: "Needed for integration"
```

--------------------------------

### Initialize Runtm Project

Source: https://context7.com/runtm-ai/runtm/llms.txt

Command to initialize a new Runtm project from various templates such as `backend-service`, `static-site`, and `web-app`. It allows specifying the project name and path, and outlines the typical project structure created.

```bash
# Initialize with backend-service template
runtm init backend-service

# Initialize with specific project name
runtm init backend-service --name my-api

# Initialize in specific directory
runtm init static-site --path ./my-site

# Available templates: backend-service, static-site, web-app, docker
runtm init web-app

# Project structure created:
# my-project/
# ├── runtm.yaml           # Deployment manifest
# ├── runtm.discovery.yaml # Search metadata
# ├── Dockerfile           # Container build
# ├── pyproject.toml       # Python dependencies
# ├── app/                 # Application code
# ├── tests/               # Tests
# ├── AGENT.md             # AI IDE instructions
# └── CLAUDE.md            # Claude Code instructions
```

--------------------------------

### Declare Environment Schema in runtm.yaml

Source: https://github.com/runtm-ai/runtm/blob/main/templates/docker/CLAUDE.md

Example snippet for the `runtm.yaml` file demonstrating how to declare an environment variable schema. It shows how to define a variable named 'DATABASE_URL', specifying its type, whether it's required, and if it should be treated as a secret.

```yaml
# runtm.yaml
env_schema:
  - name: DATABASE_URL
    type: string
    required: true
    secret: true       # Redacted from logs
    description: "Database connection"
```

--------------------------------

### Create Deployment via REST API (Python)

Source: https://context7.com/runtm-ai/runtm/llms.txt

Creates a new deployment using the `requests` library in Python. This example demonstrates uploading manifest and artifact files, and sending secrets as part of the request.

```python
# Python example
import requests

with open("runtm.yaml", "rb") as manifest, open("artifact.zip", "rb") as artifact:
    response = requests.post(
        "https://app.runtm.com/api/v0/deployments",
        headers={"Authorization": "Bearer runtm_xxx"},
        files={
            "manifest": ("runtm.yaml", manifest),
            "artifact": ("artifact.zip", artifact),
        },
        data={
            "secrets": '{"DATABASE_URL": "postgres://..."}'
        }
    )

data = response.json()
print(f"Deployment {data['deployment_id']} created")
```

--------------------------------

### Runtm Docker Compose Service Management Commands

Source: https://github.com/runtm-ai/runtm/blob/main/docs/self-hosting/docker-compose.mdx

A collection of commands for managing Runtm services when using Docker Compose. These commands facilitate starting, stopping, restarting, rebuilding images, resetting the database, viewing logs, and running migrations.

```bash
# Start all services
./scripts/dev.sh up

# Stop all services
./scripts/dev.sh down

# Restart all services
./scripts/dev.sh restart

# Rebuild images and restart
./scripts/dev.sh rebuild

# Drop all data and reset database
./scripts/dev.sh reset-db

# View logs (all or specific service)
./scripts/dev.sh logs [service]

# Run database migrations manually
./scripts/dev.sh migrate

# Run test suite
./scripts/dev.sh test

# Run linter
./scripts/dev.sh lint

# Format code
./scripts/dev.sh format
```

--------------------------------

### Basic Prompt Execution with runtm-agents

Source: https://github.com/runtm-ai/runtm/blob/main/packages/agents/README.md

Demonstrates how to get an adapter for 'claude-code', check if it's installed, and run a prompt asynchronously. It iterates through the output streams, printing different types of content like text, tool usage, errors, and results.

```python
from runtm_agents import get_adapter, run_prompt

# Get an adapter
adapter = get_adapter("claude-code")

# Check if installed
if adapter.check_installed():
    print("Claude Code is available")

# Run a prompt
import asyncio
from pathlib import Path

async def main():
    workspace = Path("./my-project")

    async for output in run_prompt(
        workspace=workspace,
        prompt="Create a simple hello world script",
        agent_type="claude-code",
    ):
        print(f"[{output.type}] {output.content}")

asyncio.run(main())

```

--------------------------------

### Local Development Commands (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/templates/web-app/CLAUDE.md

Provides commands for running the Runtm web application locally. It recommends using `runtm run` for a unified start and offers manual commands for starting the backend (FastAPI) and frontend (Next.js) separately.

```bash
# Recommended: starts both frontend and backend
# Uses Bun if available (3x faster), falls back to npm
runtm run

# Or manually in two terminals:
# Terminal 1: cd backend && pip install -e . && uvicorn app.main:app --reload --port 8080
# Terminal 2: cd frontend && bun install && bun run dev  # or npm if no bun
```

--------------------------------

### Local Development Server (Bash)

Source: https://github.com/runtm-ai/runtm/blob/main/docs/templates/web-app.mdx

Command to start both the frontend and backend development servers simultaneously. The frontend will be accessible at http://localhost:3000 and the backend at http://localhost:8080.

```bash
# Run both frontend and backend
runtm run
```