runtm

https://docs.runtm.com
Admin
Documentation for runtm, a platform offering cloud APIs, concepts, guides, and open-source tools for...
Tokens:266,761
Snippets:2,585
Trust Score:6.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### OAuth Install Response Example

Source: https://docs.runtm.com/cloud-api/context/knowledge/oauth-install

This is an example of a successful 200 OK response when initiating an OAuth install. It contains the `install_url` to redirect the user for consent and a signed `state` token for security.

```json
{
  "install_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiJ9..."
}
```

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

### Fetch Installation Token using JavaScript

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-token

This JavaScript example shows how to fetch an installation token using the `fetch` API. It includes the necessary Authorization header and parses the JSON response.

```javascript
const installationId = "inst_01J...";

const resp = await fetch(
  `https://app.runtm.com/api/github-app/installations/${installationId}/token`,
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
    },
  }
);
const data = await resp.json();
```

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

### List Sessions

Source: https://docs.runtm.com/cloud-api/overview

Make your first API call by listing the sessions your API key can see. This is a basic example to get started.

```bash
curl https://app.runtm.com/api/cloud/sessions \
  -H "Authorization: Bearer runtm_xxx"
```

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

### Sample JSON Response for Installations List

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installations-list

This is an example of the JSON response you can expect when listing GitHub App installations. It includes details for each installation, such as its ID, account type, and creation timestamp.

```json
{
  "installations": [
    {
      "id": "inst_01J...",
      "installation_id": 12345678,
      "account_type": "Organization",
      "account_login": "acme-corp",
      "avatar_url": "https://avatars.githubusercontent.com/u/12345",
      "created_at": "2026-04-15T10:00:00Z",
      "configure_url": "https://github.com/organizations/acme-corp/settings/installations/12345678",
      "is_personal": false
    }
  ],
  "total": 1
}
```

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

### Start Development Server with JavaScript

Source: https://docs.runtm.com/cloud-api/sessions/run-server

Initiate a development server using the Fetch API in JavaScript. This example demonstrates setting the request method, headers, and the JSON body.

```javascript
const response = await fetch(
    "https://app.runtm.com/api/cloud/sessions/ses_abc123/run-server",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer runtm_xxx",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ command: "npm run dev", port: 3000 }),
    }
  );

  const data = await response.json();
  console.log(`Server running at ${data.url}`);
```

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

### OAuth Install

Source: https://docs.runtm.com/cloud-api/context/knowledge/oauth-install

Starts an OAuth connection flow for a specified knowledge provider, generating a signed install URL for the user to begin the consent process.

```APIDOC
## POST /api/knowledge/oauth/{provider_id}/{auth_method_id}/install

### Description
Starts an OAuth connection flow for a specified knowledge provider, generating a signed install URL for the user to begin the consent process.

### Method
POST

### Endpoint
/api/knowledge/oauth/{provider_id}/{auth_method_id}/install

### Parameters
#### Path Parameters
- **provider_id** (string) - Required - Provider identifier from the catalog (e.g. "bigquery").
- **auth_method_id** (string) - Required - OAuth auth method identifier from the provider's catalog entry. Must have `auth_kind: "oauth"`.

#### Query Parameters
None

#### Headers
- **X-Organization-Id** (string) - Required - The organization to connect the integration to.
- **Authorization** (string) - Required - Bearer token for authentication.

#### Request Body
- **scope** (string) - Optional - Defaults to "org". Use `"org"` for a shared integration or `"personal"` for a user-scoped one.
- **display_name** (string) - Optional - Human-readable name (max 200 characters).
- **provider_metadata** (object) - Optional - Defaults to `{}`. Provider-specific configuration carried through the OAuth flow.

### Request Example
```json
{
  "scope": "org",
  "display_name": "BigQuery (OAuth)",
  "provider_metadata": {
    "project_id": "my-gcp-project"
  }
}
```

### Response
#### Success Response (200)
- **install_url** (string) - Required - URL to redirect the user's browser to for OAuth consent.
- **state** (string) - Required - HMAC-signed state token. Passed through the OAuth flow and verified on callback.

#### Response Example
```json
{
  "install_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=...",
  "state": "eyJhbGciOiJIUzI1NiJ9..."
}
```
```

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

### Start Session with Python

Source: https://docs.runtm.com/cloud-api/sessions/v2-start

Initiate a session using Python's requests library. This example shows how to make the POST request and print the sandbox state.

```python
import requests

response = requests.post(
    "https://app.runtm.com/api/v2/sessions/86e11104-.../start",
    headers={"Authorization": "Bearer runtm_xxx"},
)

session = response.json()
print(f"Sandbox {session['sandbox']['sandbox_id']} is {session['state']}")
```

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

### Start Session with JavaScript

Source: https://docs.runtm.com/cloud-api/sessions/v2-start

Start a session using the fetch API in JavaScript. This example demonstrates making the request and logging the sandbox ID and state.

```javascript
const response = await fetch(
  "https://app.runtm.com/api/v2/sessions/86e11104-.../start",
  { method: "POST", headers: { "Authorization": "Bearer runtm_xxx" } }
);

const session = await response.json();
console.log(`Sandbox ${session.sandbox.sandbox_id} is ${session.state}`);
```

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

### Delete Installation Response Example

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-delete

Example of a successful response when deleting a GitHub App installation.

```json
{
  "message": "Installation removed",
  "id": "inst_01J..."
}
```

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

### API Response Example

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-token

A successful response contains the installation access token and its expiration timestamp in ISO 8601 format.

```json
{
  "access_token": "ghs_xxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-05-09T19:00:00Z"
}
```

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

### Clone Repository and Start Services

Source: https://docs.runtm.com/open-source/self-hosting/docker-compose

Clone the Runtime repository, set up the environment file, and start all services using the development script.

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

cp infra/local.env.example .env

vim .env

./scripts/dev.sh up
```

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

### Response Example for Run Server

Source: https://docs.runtm.com/cloud-api/sessions/run-server

This JSON object shows a successful response when starting a development server, including the session ID, command, port, and the public URL.

```json
{
  "session_id": "ses_abc123",
  "command": "npm run dev",
  "port": 3000,
  "url": "https://ses-abc123-3000.runtm.dev"
}
```

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

### Response Example for Listing Repositories

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-repos

This is an example of a successful JSON response when listing repositories for a GitHub App installation. It includes repository details, total count, and pagination information.

```json
{
  "repos": [
    {
      "id": 987654,
      "name": "backend",
      "full_name": "acme-corp/backend",
      "private": true,
      "description": "Main backend API",
      "default_branch": "main",
      "html_url": "https://github.com/acme-corp/backend",
      "language": "Python",
      "updated_at": "2026-05-09T12:00:00Z",
      "size": 15400
    }
  ],
  "total_count": 12,
  "page": 1,
  "per_page": 30,
  "has_next": false
}
```

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

### Start All Services

Source: https://docs.runtm.com/open-source/self-hosting/docker-compose

Use the dev script to start all Runtime services. Migrations are run automatically.

```bash
./scripts/dev.sh up
```

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

### Linear OAuth Install URL Response Example

Source: https://docs.runtm.com/cloud-api/integrations/linear/oauth-install

Example JSON response containing the Linear OAuth authorization URL. This URL should be used to redirect the user for authorization.

```json
{
  "url": "https://linear.app/oauth/authorize?client_id=xxx&redirect_uri=...&response_type=code&scope=read,write,issues:create,app:assignable,app:mentionable&state=..."
}
```

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

### Sample Response for Get Session Instructions

Source: https://docs.runtm.com/cloud-api/sessions/instructions-get

This is an example of a successful response when retrieving custom instructions for a session. It includes the session ID and the custom instructions text, or `null` if no instructions are set.

```json
{
  "session_id": "ses_abc123",
  "instructions": "Use TypeScript strict mode. Prefer functional components with hooks. Write tests for all new functions."
}
```

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

### Install runtm using uv

Source: https://docs.runtm.com/open-source/cli/overview

Recommended installation method using the uv package manager.

```bash
uv tool install runtm
```

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

### Discovery File Example

Source: https://docs.runtm.com/open-source/cli/search

An example of the runtm.discovery.yaml file, defining metadata for a deployment.

```yaml
# runtm.discovery.yaml
description: |
  Stripe webhook handler that processes payment events
  and updates our database in real-time.

summary: "Real-time Stripe payment webhook processor"

capabilities:
  - "Process Stripe webhooks"
  - "Update payment status"
  - "Send email notifications"

use_cases:
  - "E-commerce payment tracking"
  - "Subscription billing"

tags:
  - stripe
  - webhook
  - payments
  - api

```

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

### Configuration File Example

Source: https://docs.runtm.com/open-source/cli/config

An example of the ~/.runtm/config.yaml file structure. This file stores persistent CLI settings.

```yaml
api_url: https://app.runtm.com/api
default_template: backend-service
default_runtime: python
```

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

### Get GitHub App Installations List

Source: https://docs.runtm.com/concepts/integrations

Retrieves a list of GitHub App installations associated with the organization. This is part of the GitHub App integration setup.

```APIDOC
## GET /cloud-api/integrations/github-app/installations-list

### Description
Retrieves a list of all GitHub App installations for the organization.

### Method
GET

### Endpoint
/cloud-api/integrations/github-app/installations-list

### Response
#### Success Response (200)
- **installations** (array) - A list of GitHub App installations.
  - **id** (integer) - The installation ID.
  - **account** (object) - Information about the GitHub account.
    - **login** (string) - The account login name.
    - **type** (string) - The account type (e.g., 'Organization').

#### Response Example
{
  "installations": [
    {
      "id": 12345,
      "account": {
        "login": "example-org",
        "type": "Organization"
      }
    }
  ]
}
```

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

### Quick Start with Runtm CLI

Source: https://docs.runtm.com/open-source/templates/static-site

Initialize and run the static-site template using the runtm CLI. Navigate into the created directory and start the development server.

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

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

### Initialize and Run Web App Template

Source: https://docs.runtm.com/open-source/templates/web-app

Use this command to quickly set up and start the web-app template locally. It initializes the project, navigates into the directory, and runs the application.

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

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

### Get Slack OAuth Install URL (Python)

Source: https://docs.runtm.com/cloud-api/integrations/slack/oauth-install

This Python script uses the requests library to get the Slack OAuth install URL. It prints the redirect URL from the JSON response. Requires `SLACK_CLIENT_ID` to be configured.

```python
import requests

resp = requests.get(
    "https://app.runtm.com/api/v1/slack/oauth/install-url",
    headers={
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
    },
)
data = resp.json()
print(f"Redirect user to: {data['url']}")
```

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

### Install Python SDK

Source: https://docs.runtm.com/open-source/api/overview

Install the Runtime Python SDK using pip. This module can be used programmatically.

```bash
pip install runtm
```

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

### Post-initialization commands

Source: https://docs.runtm.com/open-source/cli/init

Commands to navigate into the project directory, run it locally, and deploy it.

```bash
# Enter the project directory
cd my-project

# Run locally
runtm run

# Deploy when ready
runtm deploy
```

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

### Get Linear OAuth Install URL

Source: https://docs.runtm.com/cloud-api/integrations/linear/oauth-install

Returns the Linear OAuth authorization URL for the managed Runtime app. After the user authorizes on Linear, they are redirected back to complete the integration setup. Requires org admin role and the `integrations:write` scope. Requires organization context via the `X-Organization-Id` header.

```APIDOC
## GET /api/v1/linear/oauth/install-url

### Description
Get the OAuth URL to install the Linear integration. Returns the Linear OAuth authorization URL for the managed Runtime app. After the user authorizes on Linear, they are redirected back to complete the integration setup.

### Method
GET

### Endpoint
/api/v1/linear/oauth/install-url

### Parameters
#### Header Parameters
- **Authorization** (string, required) - Bearer token for authentication.
- **X-Organization-Id** (string, required) - The organization to install the integration for.

#### Query Parameters
- **dev_proxy_url** (string, optional) - Dev server URL for OAuth proxy redirect during local development.

### Response
#### Success Response (200)
- **url** (string, required) - Linear OAuth authorization URL. Redirect the user here.

### Request Example
```bash
curl "https://app.runtm.com/api/v1/linear/oauth/install-url" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "X-Organization-Id: org_abc123"
```

### Response Example
```json
{
  "url": "https://linear.app/oauth/authorize?client_id=xxx&redirect_uri=...&response_type=code&scope=read,write,issues:create,app:assignable,app:mentionable&state=..."
}
```
```

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

### Initialize and Run Backend Service

Source: https://docs.runtm.com/open-source/templates/backend-service

Quick start commands to initialize, navigate into, and run the backend-service template locally.

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

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

### Initiate OAuth Install (JavaScript)

Source: https://docs.runtm.com/cloud-api/context/knowledge/oauth-install

This JavaScript code snippet demonstrates how to initiate an OAuth install using the `fetch` API. It sends a POST request with appropriate headers and a JSON stringified body. The `install_url` from the response is used for user redirection.

```javascript
const resp = await fetch(
    "https://app.runtm.com/api/knowledge/oauth/bigquery/google_oauth/install",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        scope: "org",
        display_name: "BigQuery (OAuth)",
        provider_metadata: { project_id: "my-gcp-project" },
      }),
    }
  );
  const data = await resp.json();
  // Redirect user to data.install_url
```

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

### Get Slack OAuth Install URL (cURL)

Source: https://docs.runtm.com/cloud-api/integrations/slack/oauth-install

Use this cURL command to fetch the Slack OAuth install URL. Ensure you include the Authorization and X-Organization-Id headers.

```bash
curl "https://app.runtm.com/api/v1/slack/oauth/install-url" \
    -H "Authorization: Bearer runtm_xxx" \
    -H "X-Organization-Id: org_abc123"
```

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

### Initialize a Backend Service Template

Source: https://docs.runtm.com/open-source/templates/overview

Use this command to initialize a new project with the 'backend-service' template. Navigate into the project directory and deploy it.

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

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

### Run Server

Source: https://docs.runtm.com/llms.txt

Start a development server in the sandbox.

```APIDOC
## Run Server

### Description
Start a development server in the sandbox.

### Endpoint
/sessions/run-server

### Method
POST

### Parameters
#### Request Body
- **sessionId** (string) - Required - The ID of the session.
- **command** (string) - Required - The command to run the development server.
```

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

### Get Session Environment Variables (JavaScript)

Source: https://docs.runtm.com/cloud-api/sessions/env-vars-get

This JavaScript example shows how to use the fetch API to get session environment variables. It then logs each key-value pair to the console.

```javascript
const response = await fetch(
  "https://app.runtm.com/api/cloud/sessions/ses_abc123/env-vars",
  {
    headers: { "Authorization": "Bearer runtm_xxx" },
  }
);

const { env_vars } = await response.json();
Object.entries(env_vars).forEach(([k, v]) => console.log(`${k}=${v}`));
```

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

### Get Token for Repo

Source: https://docs.runtm.com/cloud-api/integrations/github-app/token-for-repo

Fetches a GitHub App installation access token scoped to a specific repository owner. It searches for the appropriate installation and returns a token with its expiry timestamp.

```APIDOC
## GET /api/github-app/token-for-repo

### Description
Get an installation access token scoped to a specific repo owner. Finds the GitHub App installation that has access to repos owned by the specified user or organization, and returns its access token. Searches org-shared installations first, then personal ones.

### Method
GET

### Endpoint
/api/github-app/token-for-repo

### Parameters
#### Query Parameters
- **repo_owner** (string) - Required - GitHub username or organization that owns the repository.

#### Headers
- **X-Organization-Id** (string) - Optional - Check org-shared installations first.
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **access_token** (string) - Required - GitHub App installation access token.
- **expires_at** (string) - Required - ISO 8601 token expiry timestamp.

### Request Example
```bash
curl "https://app.runtm.com/api/github-app/token-for-repo?repo_owner=acme-corp" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "X-Organization-Id: org_abc123"
```

```python
import requests

resp = requests.get(
    "https://app.runtm.com/api/github-app/token-for-repo",
    params={"repo_owner": "acme-corp"},
    headers={
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
    },
)
print(resp.json())
```

```javascript
const resp = await fetch(
  "https://app.runtm.com/api/github-app/token-for-repo?repo_owner=acme-corp",
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
      "X-Organization-Id": "org_abc123",
    },
  }
);
const data = await resp.json();
```

### Response Example
```json
{
  "access_token": "ghs_xxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-05-09T19:00:00Z"
}
```
```

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

### Fetch Installation Token using Python

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-token

This Python script demonstrates how to retrieve an installation token using the `requests` library. It prints the token's expiry time upon successful retrieval.

```python
import requests

installation_id = "inst_01J..."

resp = requests.get(
    f"https://app.runtm.com/api/github-app/installations/{installation_id}/token",
    headers={"Authorization": "Bearer runtm_xxx"},
)
data = resp.json()
print(f"Token expires at: {data['expires_at']}")
```

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

### Initiate OAuth Install (Python)

Source: https://docs.runtm.com/cloud-api/context/knowledge/oauth-install

This Python script uses the `requests` library to send a POST request for initiating an OAuth install. It includes necessary headers and a JSON body. The `install_url` from the response should be used to redirect the user.

```python
import requests

resp = requests.post(
    "https://app.runtm.com/api/knowledge/oauth/bigquery/google_oauth/install",
    headers={
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
        "Content-Type": "application/json",
    },
    json={
        "scope": "org",
        "display_name": "BigQuery (OAuth)",
        "provider_metadata": {"project_id": "my-gcp-project"},
    },
)
data = resp.json()
# Redirect user to data["install_url"]
```

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

### Get Installation Token

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-token

Retrieves a short-lived access token for a specific GitHub App installation. This token is cached and automatically refreshed when it expires. The required scope for this operation is `integrations:read`.

```APIDOC
## GET /api/github-app/installations/{installation_id}/token

### Description
Fetches a short-lived access token for a GitHub App installation. Tokens are cached and auto-refreshed when expired.

### Method
GET

### Endpoint
/api/github-app/installations/{installation_id}/token

### Parameters
#### Path Parameters
- **installation_id** (string) - Required - Internal installation ID.

#### Request Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer runtm_xxx`).

### Response
#### Success Response (200)
- **access_token** (string) - Required - GitHub App installation access token.
- **expires_at** (string) - Required - ISO 8601 token expiry timestamp.

#### Response Example
```json
{
  "access_token": "ghs_xxxxxxxxxxxxxxxxxxxx",
  "expires_at": "2026-05-09T19:00:00Z"
}
```
```

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

### Create and Start a Session (Python)

Source: https://docs.runtm.com/guides/managing-sessions-at-scale

Use the Start endpoint to create a session and wait until it is running and the dev server is ready. This handles state transitions transparently.

```Python
import requests

API_KEY = "runtm_xxx"
BASE = "https://app.runtm.com/api"
headers = {"Authorization": f"Bearer {API_KEY}"}

session = requests.post(
    f"{BASE}/sessions",
    headers=headers,
    json={"agent": "claude-code", "source": "api"},
).json()

ready = requests.post(
    f"{BASE}/sessions/{session['id']}/start",
    headers=headers,
).json()

print(f"State: {ready['state']}, preview: {ready.get('preview_url')}")
```

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

### Start Session (legacy)

Source: https://docs.runtm.com/llms.txt

Legacy cold-start endpoint. Prefer the v2 sandbox lifecycle endpoint.

```APIDOC
## Start Session (legacy)

### Description
Legacy cold-start endpoint - prefer the v2 sandbox lifecycle endpoint.

### Endpoint
/sessions/start

### Method
POST

### Parameters
#### Request Body
- **templateId** (string) - Required - The ID of the template to start the session from.
```

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

### Get Slack OAuth Install URL (JavaScript)

Source: https://docs.runtm.com/cloud-api/integrations/slack/oauth-install

This JavaScript snippet fetches the Slack OAuth install URL using the Fetch API. It retrieves the URL from the JSON response. Requires `SLACK_CLIENT_ID` to be configured.

```javascript
const resp = await fetch(
  "https://app.runtm.com/api/v1/slack/oauth/install-url",
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
      "X-Organization-Id": "org_abc123",
    },
  }
);
const data = await resp.json();
```

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

### Initialize backend-service in current directory

Source: https://docs.runtm.com/open-source/cli/init

Example of initializing a backend-service project in the current directory.

```bash
# Initialize backend service in current directory
runtm init backend-service
```

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

### Get Session using JavaScript

Source: https://docs.runtm.com/cloud-api/sessions/get

This JavaScript example shows how to use the fetch API to get session details. It logs the session name and state to the console. Remember to use your valid Bearer token.

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

const session = await response.json();
console.log(`${session.name} - ${session.state}`);
```

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

### Get Linear OAuth Install URL (Python)

Source: https://docs.runtm.com/cloud-api/integrations/linear/oauth-install

This Python script uses the requests library to get the Linear OAuth authorization URL. It demonstrates how to set the required headers and extract the URL from the JSON response.

```python
import requests

resp = requests.get(
    "https://app.runtm.com/api/v1/linear/oauth/install-url",
    headers={
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
    },
)
data = resp.json()
print(f"Redirect user to: {data['url']}")
```

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

### Ready Deployment Output

Source: https://docs.runtm.com/open-source/cli/status

Example output when a deployment is ready and active.

```text
Deployment: dep_abc123xyz

  Name:     my-api
  Status:   ● ready
  URL:      https://my-api-xyz123.fly.dev
  Version:  3
  Template: backend-service
  Runtime:  python
  Tier:     standard

  Created:  2024-01-15 10:30:00 UTC
  Ready:    2024-01-15 10:32:15 UTC (2m 15s)
```

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

### Define New API Routes

Source: https://docs.runtm.com/open-source/templates/backend-service

Example of creating a new API router for 'items' with GET and POST endpoints.

```python
# app/api/v1/items.py
from fastapi import APIRouter

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/")
async def list_items():
    return {"items": []}

@router.post("/")
async def create_item(name: str):
    return {"id": 1, "name": name}
```

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

### Go Dockerfile Example

Source: https://docs.runtm.com/open-source/templates/docker

A multi-stage Dockerfile for a Go application. It first builds the Go binary and then copies it to a minimal Alpine image. Ensure the exposed port matches the manifest.

```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"]
```

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

### Get Resolved Provider Key (JavaScript)

Source: https://docs.runtm.com/cloud-api/provider-keys/resolved

This JavaScript example shows how to use the fetch API to get the resolved provider key. It logs the key source and preview if a key is found, otherwise it indicates that no key is available.

```javascript
const response = await fetch(
    "https://app.runtm.com/api/cloud/user/provider-keys/anthropic/resolved",
    {
      headers: {
        "Authorization": "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
      },
    }
  );

  const data = await response.json();
  if (data.has_key) {
    console.log(`Using ${data.source} key: ${data.key_preview}`);
  } else {
    console.log("No key available");
  }
```

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

### Initialize backend-service with a project name

Source: https://docs.runtm.com/open-source/cli/init

Example of initializing a backend-service project and specifying a custom project name using the --name option.

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

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

### GitHub User Token Status Response Example

Source: https://docs.runtm.com/cloud-api/integrations/github-user-tokens/user-token-status

This is an example of a successful response when checking the GitHub user token status. It indicates the token is connected, provides the username, lists the scopes, and confirms if a GitHub App installation exists.

```json
{
  "connected": true,
  "username": "octocat",
  "scopes": "repo,read:user,read:org",
  "has_installation": true
}
```

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

### Create and Start a Session (JavaScript)

Source: https://docs.runtm.com/guides/managing-sessions-at-scale

Use the Start endpoint to create a session and wait until it is running and the dev server is ready. This handles state transitions transparently.

```javascript
const API_KEY = "runtm_xxx";
const BASE = "https://app.runtm.com/api";
const headers = { Authorization: `Bearer ${API_KEY}` };

const session = await fetch(`${BASE}/sessions`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ agent: "claude-code", source: "api" }),
}).then((r) => r.json());

const ready = await fetch(`${BASE}/sessions/${session.id}/start`, {
    method: "POST",
    headers,
}).then((r) => r.json());

console.log(`State: ${ready.state}, preview: ${ready.preview_url}`);
```

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

### Response Example for Listing Repositories

Source: https://docs.runtm.com/cloud-api/integrations/github-app/repos-list

This JSON structure represents a successful response when listing repositories accessible via GitHub App installations.

```json
{
  "installations": [
    {
      "installation": {
        "id": "inst_01J...",
        "installation_id": 12345678,
        "account_type": "Organization",
        "account_login": "acme-corp",
        "avatar_url": "https://avatars.githubusercontent.com/u/12345",
        "created_at": "2026-04-15T10:00:00Z",
        "configure_url": "https://github.com/organizations/acme-corp/settings/installations/12345678",
        "is_personal": false
      },
      "repos": [
        {
          "id": 987654,
          "name": "backend",
          "full_name": "acme-corp/backend",
          "private": true,
          "description": "Main backend API",
          "default_branch": "main",
          "html_url": "https://github.com/acme-corp/backend",
          "language": "Python",
          "updated_at": "2026-05-09T12:00:00Z",
          "size": 15400
        }
      ],
      "total_count": 1
    }
  ]
}
```

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

### Main FastAPI Application Setup

Source: https://docs.runtm.com/open-source/templates/backend-service

The entry point for the FastAPI application, setting up logging and including routers for health checks and API routes.

```python
from fastapi import FastAPI
from app.api.v1 import health, routes
from app.core.logging import setup_logging

setup_logging()

app = FastAPI(
    title="My API",
    version="1.0.0",
    docs_url="/docs",
    openapi_url="/openapi.json",
)

app.include_router(health.router)
app.include_router(routes.router, prefix="/api/v1")
```

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

### Get GitHub User Token Status

Source: https://docs.runtm.com/cloud-api/integrations/github-user-tokens/user-token-status

Retrieves the connection status of the user's GitHub token and indicates if a GitHub App installation exists for this user.

```APIDOC
## GET /api/github-app/user-token-status

### Description
Returns the connection status of the user's GitHub token without exposing the actual token. Also indicates whether a GitHub App installation exists for this user.

### Method
GET

### Endpoint
/api/github-app/user-token-status

### Headers
- **Authorization** (string, required): Bearer runtm_xxx

### Scopes
`integrations:read`

### Response
#### Success Response (200)
- **connected** (boolean, required) - Whether a GitHub token is stored for this user.
- **username** (string) - GitHub username (only when connected).
- **scopes** (string) - Token scopes (e.g. "repo,read:user,read:org").
- **has_installation** (boolean, required) - Whether a GitHub App installation exists for this user.

### Response Example
```json
{
  "connected": true,
  "username": "octocat",
  "scopes": "repo,read:user,read:org",
  "has_installation": true
}
```
```

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

### Initialize static-site in a specific directory

Source: https://docs.runtm.com/open-source/cli/init

Example of initializing a static-site project and specifying a target directory using the --path option.

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

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

### Backend API Endpoint for Items

Source: https://docs.runtm.com/open-source/templates/web-app

A FastAPI backend endpoint for listing items. This example shows a basic GET request handler that depends on a database session.

```python
# backend/app/api/v1/items.py
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session
from app.db import get_db

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/")
def list_items(db: Session = Depends(get_db)):
    # Your logic here
    return []
```

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

### Slack OAuth Install URL Response

Source: https://docs.runtm.com/cloud-api/integrations/slack/oauth-install

Example JSON response containing the Slack OAuth authorization URL. Redirect the user to this URL to initiate the authorization process.

```json
{
  "url": "https://slack.com/oauth/v2/authorize?client_id=xxx&scope=app_mentions:read,chat:write,channels:read,...&redirect_uri=...&state=..."
}
```

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

### Building Deployment Output

Source: https://docs.runtm.com/open-source/cli/status

Example output when a deployment is currently in the building process.

```text
Deployment: dep_abc123xyz

  Name:     my-api
  Status:   ◐ building
  Version:  4

  Created:  2024-01-15 14:20:00 UTC

  Building... 45s elapsed
```

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

### Response for Setting User Instructions

Source: https://docs.runtm.com/cloud-api/context/user-instructions-set

This is an example of a successful response when setting user instructions. It includes the updated instructions and the timestamp of the update.

```json
{
  "instructions": "Always use TypeScript. Prefer functional components with hooks.",
  "updated_at": "2026-05-09T18:00:00Z"
}
```

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

### Get Linear OAuth Install URL (cURL)

Source: https://docs.runtm.com/cloud-api/integrations/linear/oauth-install

Use this cURL command to fetch the Linear OAuth authorization URL. Ensure you include the necessary Authorization and X-Organization-Id headers.

```bash
curl "https://app.runtm.com/api/v1/linear/oauth/install-url" \
    -H "Authorization: Bearer runtm_xxx" \
    -H "X-Organization-Id: org_abc123"
```

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

### Successful Response Example

Source: https://docs.runtm.com/cloud-api/integrations/github-app/installation-add-repo

This JSON object represents a successful response when adding a repository to a GitHub App installation. It indicates the operation's success and provides a confirmation message.

```json
{
  "success": true,
  "message": "Repository 'acme-corp/new-repo' added to GitHub App"
}
```

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

### Python Project Execution

Source: https://docs.runtm.com/open-source/cli/run

When `runtm run` detects a Python project, it installs dependencies using `pip` and starts the development server with `uvicorn`. Ensure your `runtm.yaml` is configured for Python.

```bash
runtm run
```

```bash
pip install -e . --quiet
uvicorn app.main:app --port 8080 --reload
```

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

### Apply Changes Output Example

Source: https://docs.runtm.com/open-source/cli/approve

Example output after successfully running `runtm approve`, indicating which changes were applied, the update to `runtm.yaml`, and the deletion of `runtm.requests.yaml`. It also provides next steps for setting secrets and deploying.

```text
Applying changes from runtm.requests.yaml...

✓ Added feature: database
✓ Added feature: auth
✓ Added env var: STRIPE_API_KEY
✓ Added env var: WEBHOOK_SECRET
✓ Added to egress allowlist: api.stripe.com

Updated runtm.yaml
Deleted runtm.requests.yaml

Next steps:
  1. Set required secrets:
     runtm secrets set STRIPE_API_KEY=sk_xxx
     runtm secrets set WEBHOOK_SECRET=whsec_xxx
     runtm secrets set AUTH_SECRET=$(openssl rand -base64 32)
  
  2. Deploy:
     runtm deploy
```

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

### Get Deployment Status with JavaScript

Source: https://docs.runtm.com/open-source/api/deployments/get

This JavaScript example uses the fetch API to retrieve deployment information. It logs the deployment state and the URL to the console. Suitable for browser or Node.js environments.

```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}`);
  }
```

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

### Fetch Team Activity (JavaScript)

Source: https://docs.runtm.com/cloud-api/activity/team-activity

This JavaScript example shows how to use the `fetch` API to get team activity data. It includes setting the necessary headers for authorization and organization context.

```javascript
const resp = await fetch(
  "https://app.runtm.com/api/cloud/sessions/telemetry/team/activity?days=30",
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
      "X-Organization-Id": "org_abc123",
    },
  }
);
const data = await resp.json();
```

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

### Project structure for static-site

Source: https://docs.runtm.com/open-source/cli/init

This illustrates the file structure created when initializing a 'static-site' project.

```bash
my-project/
├── runtm.yaml
├── runtm.discovery.yaml
├── Dockerfile
├── package.json
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   └── globals.css
├── components/
├── public/
│   └── health           # Static health file
├── README.md
├── AGENT.md
└── CLAUDE.md
```

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

### Get Slack App Manifest URL

Source: https://docs.runtm.com/cloud-api/integrations/slack/manifest

Returns a pre-filled Slack App Manifest creation URL. Use this for self-hosted Slack app setup when not using the managed OAuth flow.

```APIDOC
## GET /api/v1/slack/manifest

### Description
Returns a pre-filled Slack App Manifest creation URL. Use this for self-hosted Slack app setup when not using the managed OAuth flow.

### Method
GET

### Endpoint
/api/v1/slack/manifest

### Parameters
#### Header Parameters
- **X-Organization-Id** (string) - Required - The organization context.
- **Authorization** (string) - Required - Bearer token for authentication.

#### Query Parameters
- **app_name** (string) - Optional - Custom name for the Slack app. Max 35 characters. Defaults to "Runtime".

### Response
#### Success Response (200)
- **url** (string) - Required - Slack App Manifest creation URL.
- **interactions_url** (string) - Required - The interactivity URL to configure in the Slack app settings.

### Request Example
```bash
curl "https://app.runtm.com/api/v1/slack/manifest?app_name=My%20Bot" \
  -H "Authorization: Bearer runtm_xxx" \
  -H "X-Organization-Id: org_abc123"
```

### Response Example
```json
{
  "url": "https://api.slack.com/apps?new_app=1&manifest_yaml=...",
  "interactions_url": "https://app.runtm.com/api/v1/slack/interactions"
}
```
```

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

### Get Linear OAuth Install URL (JavaScript)

Source: https://docs.runtm.com/cloud-api/integrations/linear/oauth-install

This JavaScript snippet uses the fetch API to retrieve the Linear OAuth authorization URL. It shows how to include the Authorization and X-Organization-Id headers in the request.

```javascript
const resp = await fetch(
    "https://app.runtm.com/api/v1/linear/oauth/install-url",
    {
      headers: {
        Authorization: "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
      },
    }
  );
  const data = await resp.json();
```

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

### Example Response for 'pro' Plan

Source: https://docs.runtm.com/cloud-api/provider-keys/current-plan

This is an example JSON response when the user is on the 'pro' plan and it is active. It details feature limits and available tiers.

```json
{
  "plan_name": "pro",
  "status": "active",
  "features": {
    "max_apps": 10,
    "max_sessions": 20,
    "allowed_tiers": ["starter", "standard", "performance"],
    "collaboration": true,
    "custom_domains": true
  }
}
```

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

### Basic runtm init Command Syntax

Source: https://docs.runtm.com/open-source/cli/init

Use this command to spin up a new sandbox for your agent. You can optionally specify a template to start from.

```bash
runtm init [template]
```

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

### Linear Integration Response Example

Source: https://docs.runtm.com/cloud-api/integrations/linear/integration-get

This is a sample JSON response for a successful request to get the Linear integration status. It includes details like workspace name, actor name, and webhook status.

```json
{
  "connected": true,
  "workspace_name": "Acme Engineering",
  "actor_name": "Runtime Bot",
  "service_user_id": "usr_xyz",
  "default_github_repo": "acme-corp/backend",
  "default_template": null,
  "default_agent": "claude-code",
  "rate_limit_per_hour": 15,
  "enabled": true,
  "webhook_active": true,
  "bot_linear_user_id": "lin_usr_abc",
  "project_repo_map": {
    "proj_123": "acme-corp/frontend",
    "proj_456": "acme-corp/backend"
  }
}
```

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

### Get Organization Limits using JavaScript

Source: https://docs.runtm.com/cloud-api/guardrails/org-limits-get

This JavaScript example uses the `fetch` API to retrieve organization limits. It shows how to configure request headers and access limit data from the JSON response.

```javascript
const orgId = "org_abc123";

const resp = await fetch(
  `https://app.runtm.com/api/cloud/organizations/${orgId}/limits`,
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
      "X-Organization-Id": orgId,
    },
  }
);
const data = await resp.json();
console.log(`Max sessions per user: ${data.limits.max_sessions_per_user}`);
console.log(`Enforcement: ${data.limits.enforcement}`);
```

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

### Full Presence Tracking Example

Source: https://docs.runtm.com/cloud-api/websockets/collaboration

This JavaScript example demonstrates how to establish a WebSocket connection for collaboration, obtain a token, and handle incoming presence events like user joins, leaves, and cursor updates.

```javascript
const tokenResponse = await fetch(
  "https://app.runtm.com/api/cloud/sessions/ses_abc123/ws-token",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer runtm_sk_live_abc123...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ capability: "collaborate" }),
  }
);
const { token } = await tokenResponse.json();

const ws = new WebSocket(
  `wss://app.runtm.com/api/cloud/sessions/ses_abc123/collaborate?token=${token}`
);

const activeUsers = new Map();

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "user_joined":
      activeUsers.set(msg.user.id, msg.user);
      console.log(`${msg.user.name} joined (${msg.active_users} online)`);
      break;
    case "user_left":
      activeUsers.delete(msg.user.id);
      console.log(`${msg.user.name} left (${msg.active_users} online)`);
      break;
    case "cursor_update":
      console.log(`${msg.user_id} → ${msg.position.file}:${msg.position.line}`);
      break;
  }
};
```

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

### Fetch Slack App Manifest URL (JavaScript)

Source: https://docs.runtm.com/cloud-api/integrations/slack/manifest

This JavaScript example uses the fetch API to get the Slack App Manifest URL. It shows how to configure the request headers and query parameters for the API call.

```javascript
const resp = await fetch(
  "https://app.runtm.com/api/v1/slack/manifest?app_name=My%20Bot",
  {
    headers: {
      Authorization: "Bearer runtm_xxx",
      "X-Organization-Id": "org_abc123",
    },
  }
);
const data = await resp.json();
```

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

### List Repositories using JavaScript

Source: https://docs.runtm.com/cloud-api/integrations/github-app/repos-list

This JavaScript example demonstrates fetching repositories using the fetch API. It includes the necessary Authorization and X-Organization-Id headers.

```javascript
const resp = await fetch(
    "https://app.runtm.com/api/github-app/repos?per_page=50",
    {
      headers: {
        Authorization: "Bearer runtm_xxx",
        "X-Organization-Id": "org_abc123",
      },
    }
  );
  const data = await resp.json();
```

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

### Development Environment Configuration (.env)

Source: https://docs.runtm.com/open-source/self-hosting/configuration

Example environment variables for setting up a local development instance of Runtime. Ensure secrets like DATABASE_URL and TOKEN_PEPPER_V1 are changed for production.

```bash
# Database
DATABASE_URL=postgresql://runtm:runtm@localhost:5432/runtm

# Redis
REDIS_URL=redis://localhost:6379/0

# API
RUNTM_API_SECRET=dev-secret-change-in-production-123

# Worker
FLY_API_TOKEN=FlyV1_your_token_here
ARTIFACT_STORAGE_PATH=/tmp/runtm-artifacts

# Token Security
TOKEN_PEPPER_V1=dev-pepper-change-in-production-456

# Logging
LOG_LEVEL=DEBUG
```

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

### Get Workspace State using Python

Source: https://docs.runtm.com/cloud-api/sessions/workspace-state

This Python script demonstrates how to fetch the workspace state using the `requests` library. It iterates through the detected ports and prints their numbers and associated processes. Requires the `requests` library to be installed.

```python
import requests

response = requests.get(
    "https://app.runtm.com/api/cloud/sessions/ses_abc123/workspace-state",
    headers={"Authorization": "Bearer runtm_xxx"},
)

state = response.json()
for port in state["detected_ports"]:
    print(f"Port {port['port']} - {port['process']}")
```

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

### Search deployments by keyword

Source: https://docs.runtm.com/open-source/cli/search

Example of searching for deployments that match the keyword 'payment'.

```bash
# Search by keyword
runtm search "payment"
```

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

### Get Session Instructions using Python

Source: https://docs.runtm.com/cloud-api/sessions/instructions-get

This Python script fetches custom instructions for a session using the `requests` library. It prints the instructions if set, otherwise indicates that none are configured. Requires the `requests` library to be installed.

```python
import requests

response = requests.get(
    "https://app.runtm.com/api/cloud/sessions/ses_abc123/instructions",
    headers={"Authorization": "Bearer runtm_xxx"},
)

data = response.json()
if data["instructions"]:
    print(data["instructions"])
else:
    print("No custom instructions set")
```
Tokens:
Raw