createos

# CreateOS Platform Skills

> **Ship anything to production** — AI agents, APIs, backends, bots, MCP servers, frontends, webhooks, workers, and more.

## ⚠️ IMPORTANT: Authentication

### For AI Agents (MCP) - USE THIS
When connected via MCP (OpenClaw, MoltBot, ClawdBot, Claude), **NO API KEY NEEDED**.
The MCP server handles authentication automatically.

**MCP Endpoint:** `https://api-createos.nodeops.network/mcp`

Just call the tools directly:
```
CreateProject(...)
UploadDeploymentFiles(...)
ListProjects(...)
```

### For REST API (Scripts/External)
When calling REST endpoints directly (curl, Python requests, etc.):

```
X-Api-Key: <your-api-key>
Base URL: https://api-createos.nodeops.network
```

Get API key via MCP: `CreateAPIKey({name: "my-key", expiryAt: "2025-12-31T23:59:59Z"})`

## 🚀 Quick Start for MCP Agents

### Deploy Files Directly (Fastest)

```json
// 1. Create upload project
CreateProject({
  "uniqueName": "my-app",
  "displayName": "My App",
  "type": "upload",
  "source": {},
  "settings": {
    "runtime": "node:20",
    "port": 3000
  }
})

// 2. Upload files and deploy
UploadDeploymentFiles(project_id, {
  "files": [
    {"path": "package.json", "content": "{\"name\":\"app\",\"scripts\":{\"start\":\"node index.js\"}}"},
    {"path": "index.js", "content": "require('http').createServer((req,res)=>{res.end('Hello!')}).listen(3000)"}
  ]
})

// Result: https://my-app.createos.io is live!
```

### Deploy from GitHub (Auto-deploy on push)

```json
// 1. Get GitHub installation ID
ListConnectedGithubAccounts()
// Returns: [{installationId: "12345", ...}]

// 2. Find repo ID
ListGithubRepositories("12345")
// Returns: [{id: "98765", fullName: "myorg/myrepo", ...}]

// 3. Create VCS project
CreateProject({
  "uniqueName": "my-app",
  "displayName": "My App", 
  "type": "vcs",
  "source": {
    "vcsName": "github",
    "vcsInstallationId": "12345",
    "vcsRepoId": "98765"
  },
  "settings": {
    "runtime": "node:20",
    "port": 3000,
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "runCommand": "npm start"
  }
})

// Auto-deploys on every git push!
```

### Deploy Docker Image

```json
// 1. Create image project
CreateProject({
  "uniqueName": "my-service",
  "displayName": "My Service",
  "type": "image",
  "source": {},
  "settings": {
    "port": 8080
  }
})

// 2. Deploy image
CreateDeployment(project_id, {
  "image": "nginx:latest"
})
```

## Table of Contents

1. [Introduction](#introduction)
2. [Core Skills Overview](#core-skills-overview)
3. [Project Management Skills](#project-management-skills)
4. [Deployment Skills](#deployment-skills)
5. [Environment Management Skills](#environment-management-skills)
6. [Domain & Routing Skills](#domain--routing-skills)
7. [GitHub Integration Skills](#github-integration-skills)
8. [Analytics & Monitoring Skills](#analytics--monitoring-skills)
9. [Security Skills](#security-skills)
10. [Organization Skills (Apps)](#organization-skills-apps)
11. [API Key Management Skills](#api-key-management-skills)
12. [Common Deployment Patterns](#common-deployment-patterns)
13. [Best Practices](#best-practices)
14. [Troubleshooting & Edge Cases](#troubleshooting--edge-cases)
15. [API Quick Reference](#api-quick-reference)

---

## Introduction

### What is CreateOS?

CreateOS is a cloud deployment platform designed for rapid shipping of any workload — from simple static sites to complex multi-agent AI systems. It provides:

- **Three deployment methods**: GitHub auto-deploy, Docker images, direct file upload
- **Multi-environment support**: Production, staging, development with isolated configs
- **Built-in CI/CD**: Automatic builds and deployments on git push
- **Custom domains**: SSL/TLS included, DNS verification
- **Real-time analytics**: Request metrics, error tracking, performance monitoring
- **Security scanning**: Vulnerability detection for deployments

### Target Users

| User Type | Primary Use Cases |
|-----------|-------------------|
| **AI/ML Engineers** | Deploy agents, MCP servers, RAG pipelines, LLM services |
| **Backend Developers** | Ship APIs, microservices, webhooks, workers |
| **Frontend Developers** | Deploy SPAs, SSR apps, static sites |
| **DevOps Engineers** | Manage environments, domains, scaling, monitoring |
| **Bot Developers** | Host Discord, Slack, Telegram bots |

### Supported Technologies

**Runtimes**: `node:18`, `node:20`, `node:22`, `python:3.11`, `python:3.12`, `golang:1.22`, `golang:1.25`, `rust:1.75`, `bun:1.1`, `bun:1.3`, `static`

**Frameworks**: `nextjs`, `reactjs-spa`, `reactjs-ssr`, `vuejs-spa`, `vuejs-ssr`, `nuxtjs`, `astro`, `remix`, `express`, `fastapi`, `flask`, `django`, `gin`, `fiber`, `actix`

---

## Core Skills Overview

### 🔌 MCP Tools Available (Direct Call - No Auth Needed)

When using CreateOS via MCP (OpenClaw, Claude, etc.), these tools are available directly:

**Projects:**
- `CreateProject` - Create new project (vcs, image, or upload type)
- `ListProjects` - List all projects
- `GetProject` - Get project details
- `UpdateProject` - Update project metadata
- `UpdateProjectSettings` - Update build/runtime settings
- `DeleteProject` - Delete project

**Deployments:**
- `CreateDeployment` - Deploy Docker image (image projects)
- `TriggerLatestDeployment` - Trigger build from GitHub (vcs projects)
- `UploadDeploymentFiles` - Upload files to deploy (upload projects)
- `UploadDeploymentBase64Files` - Upload binary files as base64
- `UploadDeploymentZip` - Upload zip archive
- `ListDeployments` - List all deployments
- `GetDeployment` - Get deployment status
- `GetBuildLogs` - View build logs
- `GetDeploymentLogs` - View runtime logs
- `RetriggerDeployment` - Retry failed deployment
- `CancelDeployment` - Cancel queued/building deployment
- `WakeupDeployment` - Wake sleeping deployment

**Environments:**
- `CreateProjectEnvironment` - Create environment (production, staging, etc.)
- `ListProjectEnvironments` - List environments
- `UpdateProjectEnvironment` - Update environment config
- `UpdateProjectEnvironmentEnvironmentVariables` - Set env vars
- `UpdateProjectEnvironmentResources` - Scale CPU/memory/replicas
- `AssignDeploymentToProjectEnvironment` - Assign deployment to env
- `DeleteProjectEnvironment` - Delete environment

**Domains:**
- `CreateDomain` - Add custom domain
- `ListDomains` - List domains
- `RefreshDomain` - Verify DNS
- `UpdateDomainEnvironment` - Assign domain to environment
- `DeleteDomain` - Remove domain

**GitHub:**
- `ListConnectedGithubAccounts` - Get connected GitHub accounts
- `ListGithubRepositories` - List accessible repos
- `ListGithubRepositoryBranches` - List branches

**Apps:**
- `CreateApp` - Create app to group projects
- `ListApps` - List apps
- `AddProjectsToApp` - Add projects to app

**User:**
- `GetCurrentUser` - Get user info
- `GetQuotas` - Check usage limits
- `GetSupportedProjectTypes` - List runtimes/frameworks

### Functional Skills

| Skill Category | Capabilities |
|----------------|--------------|
| **Project Management** | Create, configure, update, delete, transfer projects |
| **Deployment** | Build, deploy, rollback, wake, cancel deployments |
| **Environment Management** | Multi-env configs, env vars, resource scaling |
| **Domain Management** | Custom domains, SSL, DNS verification |
| **GitHub Integration** | Auto-deploy, branch management, repo access |
| **Analytics** | Request metrics, error rates, performance data |
| **Security** | Vulnerability scanning, API key management |
| **Organization** | Group projects into apps, manage services |

### Technical Skills

| Skill | Description |
|-------|-------------|
| **Authentication** | API key-based auth with expiry management |
| **Build AI** | Automatic build configuration detection |
| **Dockerfile Support** | Custom container builds |
| **Environment Isolation** | Separate configs per environment |
| **Resource Management** | CPU, memory, replica scaling |

---

## Project Management Skills

### Skill: Create Projects

Create new projects with full configuration for build and runtime settings.

#### Project Types

| Type | Description | Best For |
|------|-------------|----------|
| `vcs` | GitHub-connected repository | Production apps with CI/CD |
| `image` | Docker container deployment | Pre-built images, complex deps |
| `upload` | Direct file upload | Quick prototypes, static sites |

#### VCS Project Creation

**What it does**: Links a GitHub repository for automatic deployments on push.

**Why it's useful**: Enables GitOps workflow — push to deploy with zero manual intervention.

**How to implement**:

```json
CreateProject({
  "uniqueName": "my-nextjs-app",
  "displayName": "My Next.js Application",
  "type": "vcs",
  "source": {
    "vcsName": "github",
    "vcsInstallationId": "12345678",
    "vcsRepoId": "98765432"
  },
  "settings": {
    "framework": "nextjs",
    "runtime": "node:20",
    "port": 3000,
    "directoryPath": ".",
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "runCommand": "npm start",
    "buildVars": {
      "NODE_ENV": "production",
      "NEXT_PUBLIC_API_URL": "https://api.example.com"
    },
    "runEnvs": {
      "DATABASE_URL": "postgresql://...",
      "SECRET_KEY": "..."
    },
    "ignoreBranches": ["develop", "feature/*"],
    "hasDockerfile": false,
    "useBuildAI": false
  },
  "appId": "optional-app-uuid",
  "enabledSecurityScan": true
})
```

**Prerequisites**:
- GitHub account connected via `InstallGithubApp`
- Repository access granted to CreateOS GitHub App

**Potential pitfalls**:
- Incorrect `vcsRepoId` causes deployment failures
- Missing `port` setting results in health check failures
- `buildVars` vs `runEnvs` confusion (build-time vs runtime)

#### Image Project Creation

**What it does**: Deploys pre-built Docker images without build step.

**Why it's useful**: Faster deployments, complex dependencies, existing CI pipelines.

```json
CreateProject({
  "uniqueName": "my-api-service",
  "displayName": "My API Service",
  "type": "image",
  "source": {},
  "settings": {
    "port": 8080,
    "runEnvs": {
      "API_KEY": "secret",
      "LOG_LEVEL": "info"
    }
  }
})
```

**Implications**:
- No build logs (image already built)
- Must manage image registry separately
- Version control via image tags

#### Upload Project Creation

**What it does**: Deploy by uploading files directly — no Git required.

**Why it's useful**: Quick prototypes, migrations, CI-generated artifacts.

```json
CreateProject({
  "uniqueName": "quick-prototype",
  "displayName": "Quick Prototype",
  "type": "upload",
  "source": {},
  "settings": {
    "framework": "express",
    "runtime": "node:20",
    "port": 3000,
    "installCommand": "npm install",
    "buildCommand": "npm run build",
    "buildDir": "dist",
    "useBuildAI": true
  }
})
```

### Skill: Update Project Settings

Modify build and runtime configuration without recreating projects.

```json
UpdateProjectSettings(project_id, {
  "framework": "nextjs",
  "runtime": "node:22",
  "port": 3000,
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "runCommand": "npm start",
  "buildDir": ".next",
  "buildVars": {"NODE_ENV": "production"},
  "runEnvs": {"NEW_VAR": "value"},
  "ignoreBranches": ["wip/*"],
  "hasDockerfile": false,
  "useBuildAI": false
})
```

**Edge cases**:
- Changing `runtime` triggers rebuild on next deployment
- Changing `port` requires redeployment to take effect
- `ignoreBranches` only affects future pushes

### Skill: Project Lifecycle Management

| Operation | Tool | Use Case |
|-----------|------|----------|
| List projects | `ListProjects(limit?, offset?, name?, type?, status?, app?)` | Dashboard, search |
| Get details | `GetProject(project_id)` | View full config |
| Update metadata | `UpdateProject(project_id, {displayName, description?, enabledSecurityScan?})` | Rename, toggle features |
| Delete | `DeleteProject(project_id)` | Cleanup (async deletion) |
| Check name | `CheckProjectUniqueName({uniqueName})` | Validation before create |

### Skill: Project Transfer

Transfer project ownership between users.

```
1. Owner: GetProjectTransferUri(project_id) → returns {uri, token} (valid 6 hours)
2. Owner: Share URI with recipient
3. Recipient: TransferProject(project_id, token)
4. Audit: ListProjectTransferHistory(project_id)
```

**Security implications**:
- Token expires after 6 hours
- Transfer is irreversible
- All environments and deployments transfer

---

## Deployment Skills

### Skill: Trigger Deployments

#### For VCS Projects

**Automatic** (recommended): Push to GitHub triggers deployment automatically.

**Manual trigger**:
```json
TriggerLatestDeployment(project_id, branch?)
// branch defaults to repo's default branch
```

#### For Image Projects

```json
CreateDeployment(project_id, {
  "image": "nginx:latest"
})
// Supports any valid Docker image reference:
// - nginx:latest
// - myregistry.com/myapp:v1.2.3
// - ghcr.io/org/repo:sha-abc123
```

#### For Upload Projects

**Direct files**:
```json
UploadDeploymentFiles(project_id, {
  "files": [
    {"path": "package.json", "content": "{\"name\":\"app\",...}"},
    {"path": "index.js", "content": "const express = require('express')..."},
    {"path": "public/style.css", "content": "body { margin: 0; }"}
  ]
})
```

**Base64 files** (for binary content):
```json
UploadDeploymentBase64Files(project_id, {
  "files": [
    {"path": "assets/logo.png", "content": "iVBORw0KGgo..."}
  ]
})
```

**ZIP upload**:
```json
UploadDeploymentZip(project_id, {file: zipBinaryData})
```

**Limitations**:
- Max 100 files per upload
- Use ZIP for larger projects

### Skill: Deployment Lifecycle

```
┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐
│ queued  │ →  │ building │ →  │ deploying │ →  │ deployed │
└─────────┘    └──────────┘    └───────────┘    └──────────┘
                    │                                 │
                    ↓                                 ↓
               ┌────────┐                       ┌──────────┐
               │ failed │                       │ sleeping │
               └────────┘                       └──────────┘
```

| State | Description | Actions Available |
|-------|-------------|-------------------|
| `queued` | Waiting for build slot | Cancel |
| `building` | Build in progress | Cancel, View logs |
| `deploying` | Pushing to infrastructure | Wait |
| `deployed` | Live and serving traffic | Assign to env |
| `failed` | Build or deploy error | Retry, View logs |
| `sleeping` | Idle timeout (cost saving) | Wake up |

### Skill: Deployment Operations

| Operation | Tool | Notes |
|-----------|------|-------|
| List | `ListDeployments(project_id, limit?, offset?)` | Max 20/page, paginate for more |
| Get details | `GetDeployment(project_id, deployment_id)` | Full status, timestamps, URLs |
| Retry | `RetriggerDeployment(project_id, deployment_id, settings?)` | `settings`: "project" or "deployment" |
| Cancel | `CancelDeployment(project_id, deployment_id)` | Only `queued`/`building` states |
| Delete | `DeleteDeployment(project_id, deployment_id)` | Marks for async deletion |
| Wake | `WakeupDeployment(project_id, deployment_id)` | Restarts sleeping deployment |
| Download | `DownloadDeployment(project_id, deployment_id)` | Upload projects only |

### Skill: Debug with Logs

**Build logs** — Debug compilation/build failures:
```json
GetBuildLogs(project_id, deployment_id, skip?)
// skip: number of lines to skip (for pagination)
```

**Runtime logs** — Debug application errors:
```json
GetDeploymentLogs(project_id, deployment_id, since-seconds?)
// since-seconds: look back window (default: 60)
```

**Environment logs** — Aggregate logs for an environment:
```json
GetProjectEnvironmentLogs(project_id, environment_id, since-seconds?)
```

---

## Environment Management Skills

### Skill: Create Environments

Environments provide isolated configurations for the same codebase.

**Typical setup**:
- `production` — Live traffic, max resources
- `staging` — Pre-production testing
- `development` — Feature development

#### VCS Project Environment (branch required)

```json
CreateProjectEnvironment(project_id, {
  "displayName": "Production",
  "uniqueName": "production",
  "description": "Live production environment",
  "branch": "main",
  "isAutoPromoteEnabled": true,
  "resources": {
    "cpu": 500,
    "memory": 1024,
    "replicas": 2
  },
  "settings": {
    "runEnvs": {
      "NODE_ENV": "production",
      "DATABASE_URL": "postgresql://prod-db:5432/app",
      "REDIS_URL": "redis://prod-cache:6379"
    }
  }
})
```

#### Image Project Environment (no branch)

```json
CreateProjectEnvironment(project_id, {
  "displayName": "Production",
  "uniqueName": "production",
  "description": "Live production environment",
  "resources": {
    "cpu": 500,
    "memory": 1024,
    "replicas": 2
  },
  "settings": {
    "runEnvs": {
      "NODE_ENV": "production"
    }
  }
})
```

### Skill: Resource Management

| Resource | Min | Max | Unit | Implications |
|----------|-----|-----|------|--------------|
| CPU | 200 | 500 | millicores | Higher = faster processing |
| Memory | 500 | 1024 | MB | Higher = more data in memory |
| Replicas | 1 | 3 | instances | Higher = more availability |

```json
UpdateProjectEnvironmentResources(project_id, environment_id, {
  "cpu": 500,
  "memory": 1024,
  "replicas": 3
})
```

**Scaling considerations**:
- Replicas > 1 requires stateless application design
- Memory limits cause OOM kills if exceeded
- CPU throttling occurs at limit (not killed)

### Skill: Environment Variables

```json
UpdateProjectEnvironmentEnvironmentVariables(project_id, environment_id, {
  "runEnvs": {
    "DATABASE_URL": "postgresql://...",
    "API_KEY": "new-secret-key",
    "LOG_LEVEL": "debug",
    "FEATURE_FLAG_X": "enabled"
  },
  "port": 8080  // Image projects only
})
```

**Best practices**:
- Never commit secrets to code — use `runEnvs`
- Use different values per environment
- Redeploy after changing vars for effect

### Skill: Deployment Assignment

Manually control which deployment serves an environment:

```json
AssignDeploymentToProjectEnvironment(project_id, environment_id, {
  "deploymentId": "deployment-uuid"
})
```

**Use cases**:
- Rollback to previous deployment
- Blue-green deployment switching
- Canary releases (with multiple envs)

---

## Domain & Routing Skills

### Skill: Add Custom Domains

```json
CreateDomain(project_id, {
  "name": "api.mycompany.com",
  "environmentId": "optional-env-uuid"  // Assign immediately
})
```

**Response includes DNS instructions**:
```
Add CNAME record:
  api.mycompany.com → <createos-provided-target>
```

### Skill: Domain Verification Flow

```
1. CreateDomain → Status: pending
2. Configure DNS at your registrar
3. Wait for DNS propagation (up to 48 hours)
4. RefreshDomain → Status: active (if verified)
```

```json
RefreshDomain(project_id, domain_id)
// Only available when status is "pending"
```

### Skill: Domain-Environment Assignment

Route domain traffic to specific environment:

```json
UpdateDomainEnvironment(project_id, domain_id, {
  "environmentId": "production-env-uuid"
})
// Set to null to unassign
```

**Multi-domain setup example**:
- `app.example.com` → production environment
- `staging.example.com` → staging environment
- `dev.example.com` → development environment

### Skill: Domain Operations

| Operation | Tool |
|-----------|------|
| List | `ListDomains(project_id)` |
| Verify | `RefreshDomain(project_id, domain_id)` |
| Assign | `UpdateDomainEnvironment(project_id, domain_id, {environmentId})` |
| Delete | `DeleteDomain(project_id, domain_id)` |

---

## GitHub Integration Skills

### Skill: Connect GitHub Account

```json
InstallGithubApp({
  "installationId": 12345678,
  "code": "oauth-code-from-github-redirect"
})
```

**Flow**:
1. User clicks "Connect GitHub" in CreateOS
2. Redirected to GitHub for authorization
3. GitHub redirects back with `code` and `installationId`
4. Call `InstallGithubApp` to complete connection

### Skill: Repository Discovery

```json
// 1. Get connected accounts
ListConnectedGithubAccounts()
// Returns: [{installationId, accountName, accountType}, ...]

// 2. List accessible repositories
ListGithubRepositories(installation_id)
// Returns: [{id, name, fullName, private, defaultBranch}, ...]

// 3. List branches for a repo
ListGithubRepositoryBranches(installation_id, "owner/repo", page?, per-page?, protected?)
// Returns: [{name, protected}, ...]

// 4. Get file tree (for monorepo path selection)
GetGithubRepositoryContent(installation_id, {
  "repository": "owner/repo",
  "branch": "main",
  "treeSha": "optional-tree-sha"
})
```

### Skill: Auto-Deploy Configuration

**Branch filtering** — Ignore branches from auto-deploy:

```json
UpdateProjectSettings(project_id, {
  "ignoreBranches": ["develop", "feature/*", "wip/*"]
})
```

**Auto-promote** — Automatically assign deployments to environment:

```json
CreateProjectEnvironment(project_id, {
  "branch": "main",
  "isAutoPromoteEnabled": true,
  // ... other settings
})
```

When `isAutoPromoteEnabled: true`, successful deployments from the branch automatically become active in that environment.

---

## Analytics & Monitoring Skills

### Skill: Comprehensive Analytics

```json
GetProjectEnvironmentAnalytics(project_id, environment_id, {
  "start": 1704067200,  // Unix timestamp (default: 1 hour ago)
  "end": 1704070800     // Unix timestamp (default: now)
})
```

**Returns**:
- Overall request counts
- Status code distribution
- RPM (requests per minute)
- Success percentage
- Top hit paths
- Top error paths

### Skill: Individual Metrics

| Metric | Tool | Returns |
|--------|------|---------|
| Overall requests | `GetProjectEnvironmentAnalyticsOverallRequests` | Total, 2xx, 4xx, 5xx counts |
| RPM | `GetProjectEnvironmentAnalyticsRPM` | Peak and average RPM |
| Success % | `GetProjectEnvironmentAnalyticsSuccessPercentage` | (2xx + 3xx) / total |
| Time series | `GetProjectEnvironmentAnalyticsRequestsOverTime` | Requests by status over time |
| Top paths | `GetProjectEnvironmentAnalyticsTopHitPaths` | Top 10 most accessed |
| Error paths | `GetProjectEnvironmentAnalyticsTopErrorPaths` | Top 10 error-prone |
| Distribution | `GetEnvAnalyticsReqDistribution` | Breakdown by status code |

### Skill: Performance Monitoring

**Identify issues**:
1. Check `SuccessPercentage` — drop indicates problems
2. Review `TopErrorPaths` — find problematic endpoints
3. Analyze `RequestsOverTime` — spot traffic patterns
4. Monitor `RPM` — detect traffic spikes

---

## Security Skills

### Skill: Vulnerability Scanning

**Enable scanning**:
```json
UpdateProject(project_id, {
  "enabledSecurityScan": true
})
```

**Trigger scan**:
```json
TriggerSecurityScan(project_id, deployment_id)
```

**View results**:
```json
GetSecurityScan(project_id, deployment_id)
// Returns: {status, vulnerabilities, summary}
```

**Download full report**:
```json
GetSecurityScanDownloadUri(project_id, deployment_id)
// Only when status is "successful"
// Returns signed URL for report download
```

**Retry failed scan**:
```json
RetriggerSecurityScan(project_id, deployment_id)
// Only when status is "failed"
```

---

## Organization Skills (Apps)

### Skill: Group Projects

Apps provide logical grouping for related projects and services.

```json
CreateApp({
  "name": "E-Commerce Platform",
  "description": "All services for the e-commerce system",
  "color": "#3B82F6"
})
```

### Skill: Manage App Contents

```json
// Add projects to app
AddProjectsToApp(app_id, {
  "projectIds": ["project-1-uuid", "project-2-uuid"]
})

// Remove projects
RemoveProjectsFromApp(app_id, {
  "projectIds": ["project-1-uuid"]
})

// List projects in app
ListProjectsByApp(app_id, limit?, offset?)

// Same for services
AddServicesToApp(app_id, {"serviceIds": [...]})
RemoveServicesFromApp(app_id, {"serviceIds": [...]})
ListServicesByApp(app_id, limit?, offset?)
```

### Skill: App Lifecycle

| Operation | Tool |
|-----------|------|
| List | `ListApps()` |
| Update | `UpdateApp(app_id, {name, description?, color?})` |
| Delete | `DeleteApp(app_id)` |

**Note**: Deleting an app sets `appId: null` on associated projects/services (doesn't delete them).

---

## API Key Management Skills

### Skill: Create API Keys

```json
CreateAPIKey({
  "name": "production-key",
  "description": "API key for production CI/CD",
  "expiryAt": "2025-12-31T23:59:59Z"
})
// Returns: {id, name, key, expiryAt}
// IMPORTANT: key is only shown once at creation
```

### Skill: API Key Operations

| Operation | Tool |
|-----------|------|
| List | `ListAPIKeys()` |
| Update | `UpdateAPIKey(api_key_id, {name, description?})` |
| Revoke | `RevokeAPIKey(api_key_id)` |
| Check name | `CheckAPIKeyUniqueName({uniqueName})` |

### Skill: User & Quota Management

```json
GetCurrentUser()
// Returns: user profile information

GetQuotas()
// Returns: {projects: {used, limit}, apiKeys: {used, limit}, ...}

GetSupportedProjectTypes()
// Returns: current list of supported runtimes and frameworks
```

---

## Common Deployment Patterns

### Pattern: AI Agent Deployment

```json
CreateProject({
  "uniqueName": "intelligent-agent",
  "displayName": "Intelligent Agent",
  "type": "vcs",
  "source": {"vcsName": "github", "vcsInstallationId": "...", "vcsRepoId": "..."},
  "settings": {
    "runtime": "python:3.12",
    "port": 8000,
    "installCommand": "pip install -r requirements.txt",
    "runCommand": "python -m uvicorn agent:app --host 0.0.0.0 --port 8000",
    "runEnvs": {
      "OPENAI_API_KEY": "sk-...",
      "ANTHROPIC_API_KEY": "sk-ant-...",
      "LANGCHAIN_TRACING": "true",
      "AGENT_MEMORY_BACKEND": "redis"
    }
  }
})
```

### Pattern: MCP Server Deployment

```json
CreateProject({
  "uniqueName": "my-mcp-server",
  "displayName": "Custom MCP Server",
  "type": "vcs",
  "source": {"vcsName": "github", "vcsInstallationId": "...", "vcsRepoId": "..."},
  "settings": {
    "runtime": "node:20",
    "port": 3000,
    "installCommand": "npm install",
    "runCommand": "node server.js",
    "runEnvs": {
      "MCP_TRANSPORT": "sse",
      "MCP_PATH": "/mcp"
    }
  }
})
```

**MCP Endpoint**: `https://{uniqueName}.createos.io/mcp`

### Pattern: RAG Pipeline

```json
CreateProject({
  "uniqueName": "rag-pipeline",
  "displayName": "RAG Pipeline Service",
  "type": "vcs",
  "settings": {
    "runtime": "python:3.12",
    "port": 8000,
    "runCommand": "uvicorn main:app --host 0.0.0.0 --port 8000",
    "runEnvs": {
      "PINECONE_API_KEY": "...",
      "PINECONE_ENVIRONMENT": "us-west1-gcp",
      "OPENAI_API_KEY": "...",
      "EMBEDDING_MODEL": "text-embedding-3-small",
      "CHUNK_SIZE": "512",
      "CHUNK_OVERLAP": "50"
    }
  }
})
```

### Pattern: Discord/Slack Bot

```json
CreateProject({
  "uniqueName": "discord-bot",
  "displayName": "Discord Bot",
  "type": "image",
  "source": {},
  "settings": {
    "port": 8080,
    "runEnvs": {
      "DISCORD_TOKEN": "...",
      "DISCORD_CLIENT_ID": "...",
      "BOT_PREFIX": "!",
      "LOG_CHANNEL_ID": "..."
    }
  }
})

// Deploy with:
CreateDeployment(project_id, {"image": "my-discord-bot:v1.0.0"})
```

### Pattern: Multi-Agent System

```
┌─────────────────────────────────────────────────┐
│                  App: Agent Swarm               │
├─────────────────┬─────────────────┬─────────────┤
│  Orchestrator   │   Worker Agent  │  Worker Agent│
│  (coordinator)  │   (researcher)  │  (executor) │
└────────┬────────┴────────┬────────┴──────┬──────┘
         │                 │               │
         └────── HTTP/gRPC communication ──┘
```

```json
// 1. Create app
CreateApp({"name": "Agent Swarm"})

// 2. Create orchestrator
CreateProject({
  "uniqueName": "orchestrator",
  "type": "vcs",
  "appId": app_id,
  "settings": {
    "runEnvs": {
      "WORKER_RESEARCHER_URL": "https://researcher.createos.io",
      "WORKER_EXECUTOR_URL": "https://executor.createos.io"
    }
  }
})

// 3. Create workers
CreateProject({"uniqueName": "researcher", "appId": app_id, ...})
CreateProject({"uniqueName": "executor", "appId": app_id, ...})
```

### Pattern: Blue-Green Deployment

```
1. CreateProjectEnvironment "blue" with branch "main"
2. CreateProjectEnvironment "green" with branch "main"
3. CreateDomain "app.example.com" → assign to "blue"
4. Deploy new version to "green"
5. Test via green's environment URL
6. UpdateDomainEnvironment → switch to "green"
7. "blue" becomes the standby
```

### Pattern: Rollback

```json
// 1. Find previous good deployment
ListDeployments(project_id, {limit: 10})
// Identify deployment_id of last known good

// 2. Assign to environment
AssignDeploymentToProjectEnvironment(project_id, environment_id, {
  "deploymentId": "previous-good-deployment-id"
})
```

---

## Best Practices

### Security

1. **Never hardcode secrets** — Use `runEnvs` for all sensitive data
2. **Enable security scanning** — Catch vulnerabilities early
3. **Rotate API keys** — Set reasonable expiry dates
4. **Use environment isolation** — Different secrets per environment

### Performance

1. **Right-size resources** — Start small, scale based on metrics
2. **Use replicas for availability** — Min 2 for production
3. **Monitor analytics** — Set up alerts for error rate spikes
4. **Optimize builds** — Use `npm ci` over `npm install`

### Reliability

1. **Enable auto-promote carefully** — Test in staging first
2. **Keep previous deployments** — Enable quick rollbacks
3. **Use health checks** — Ensure `port` matches app's listen port
4. **Handle sleeping deployments** — Wake or configure keep-alive

### Organization

1. **Use Apps** — Group related projects logically
2. **Naming conventions** — `{app}-{service}-{env}` pattern
3. **Document environments** — Clear descriptions for each
4. **Clean up unused** — Delete old projects and deployments

---

## Troubleshooting & Edge Cases

### Common Errors

| Error | Diagnosis | Solution |
|-------|-----------|----------|
| Build failed | `GetBuildLogs` | Fix code errors, check dependencies |
| Runtime crash | `GetDeploymentLogs` | Check startup errors, missing env vars |
| Health check fail | App not responding on port | Verify `port` setting matches app |
| 502 Bad Gateway | App crashed after deploy | Check logs, increase memory if OOM |
| Domain pending | DNS not propagated | Wait 24-48h, verify CNAME record |
| Quota exceeded | `GetQuotas` | Upgrade plan or delete unused |
| Deployment sleeping | Idle timeout | `WakeupDeployment` or add keep-alive |

### Edge Cases

**High-load scenarios**:
- Max 3 replicas per environment
- Consider external load balancer for higher scale
- Monitor RPM and adjust resources

**Monorepo projects**:
- Set `directoryPath` to subdirectory
- Use `GetGithubRepositoryContent` to explore structure

**Private npm/pip packages**:
- Add auth tokens to `buildVars`
- Use `.npmrc` or `pip.conf` in repo

**Long-running builds**:
- Build timeout is 15 minutes
- Use `hasDockerfile: true` for complex builds
- Pre-build images for image projects

---

## API Quick Reference

### Project Lifecycle
```
CreateProject → ListProjects → GetProject → UpdateProject → UpdateProjectSettings → DeleteProject
CheckProjectUniqueName | GetProjectTransferUri → TransferProject | ListProjectTransferHistory
```

### Deployment Lifecycle
```
CreateDeployment | TriggerLatestDeployment | UploadDeploymentFiles | UploadDeploymentBase64Files | UploadDeploymentZip
ListDeployments → GetDeployment → AssignDeploymentToProjectEnvironment
RetriggerDeployment | CancelDeployment | DeleteDeployment | WakeupDeployment | DownloadDeployment
GetBuildLogs | GetDeploymentLogs
```

### Environment Lifecycle
```
CreateProjectEnvironment → ListProjectEnvironments → UpdateProjectEnvironment → DeleteProjectEnvironment
CheckProjectEnvironmentUniqueName | AssignDeploymentToProjectEnvironment
UpdateProjectEnvironmentEnvironmentVariables | UpdateProjectEnvironmentResources
GetProjectEnvironmentLogs
```

### Domain Lifecycle
```
CreateDomain → ListDomains → RefreshDomain → UpdateDomainEnvironment → DeleteDomain
```

### GitHub Integration
```
InstallGithubApp → ListConnectedGithubAccounts
ListGithubRepositories → ListGithubRepositoryBranches → GetGithubRepositoryContent
```

### Analytics
```
GetProjectEnvironmentAnalytics (comprehensive)
GetProjectEnvironmentAnalyticsOverallRequests | GetProjectEnvironmentAnalyticsRPM
GetProjectEnvironmentAnalyticsSuccessPercentage | GetProjectEnvironmentAnalyticsRequestsOverTime
GetProjectEnvironmentAnalyticsTopHitPaths | GetProjectEnvironmentAnalyticsTopErrorPaths
GetEnvAnalyticsReqDistribution
```

### Security
```
TriggerSecurityScan → GetSecurityScan → GetSecurityScanDownloadUri
RetriggerSecurityScan
```

### Apps
```
CreateApp → ListApps → UpdateApp → DeleteApp
AddProjectsToApp | RemoveProjectsFromApp | ListProjectsByApp
AddServicesToApp | RemoveServicesFromApp | ListServicesByApp
```

### API Keys & User
```
CreateAPIKey → ListAPIKeys → UpdateAPIKey → RevokeAPIKey
CheckAPIKeyUniqueName | GetCurrentUser | GetQuotas | GetSupportedProjectTypes
```

### Naming Constraints

| Field | Min | Max | Pattern |
|-------|-----|-----|---------|
| Project uniqueName | 4 | 32 | `^[a-zA-Z0-9-]+$` |
| Project displayName | 4 | 48 | `^[a-zA-Z0-9 _-]+$` |
| Description | 4 | 2048 | Any text |
| Environment uniqueName | 4 | 32 | `^[a-zA-Z0-9-]+$` |
| Environment displayName | 4 | 48 | `^[a-zA-Z0-9 _-]+$` |
| API key name | 4 | 48 | `^[a-zA-Z0-9-]+$` |
| Domain name | 3 | 255 | Valid domain |

---

*Last updated: January 2025*