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.):

Authorization: Bearer <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)

// 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)

// 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

// 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
2. Core Skills Overview
3. Project Management Skills
4. Deployment Skills
5. Environment Management Skills
6. Domain & Routing Skills
7. GitHub Integration Skills
8. Analytics & Monitoring Skills
9. Security Skills
10. Organization Skills (Apps)
11. API Key Management Skills
12. Common Deployment Patterns
13. Best Practices
14. Troubleshooting & Edge Cases
15. 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

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

Technical Skills

Project Management Skills

Skill: Create Projects

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

Project Types

vcs

image

upload

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:

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.

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.

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.

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

ListProjects(limit?, offset?, name?, type?, status?, app?)

GetProject(project_id)

UpdateProject(project_id, {displayName, description?, enabledSecurityScan?})

DeleteProject(project_id)

CheckProjectUniqueName({uniqueName})

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:

TriggerLatestDeployment(project_id, branch?)
// branch defaults to repo's default branch

For Image Projects

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:

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):

UploadDeploymentBase64Files(project_id, {
  "files": [
    {"path": "assets/logo.png", "content": "iVBORw0KGgo..."}
  ]
})

ZIP upload:

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 │
               └────────┘                       └──────────┘

queued

building

deploying

deployed

failed

sleeping

Skill: Deployment Operations

ListDeployments(project_id, limit?, offset?)

GetDeployment(project_id, deployment_id)

RetriggerDeployment(project_id, deployment_id, settings?)

settings

CancelDeployment(project_id, deployment_id)

queued

building

DeleteDeployment(project_id, deployment_id)

WakeupDeployment(project_id, deployment_id)

DownloadDeployment(project_id, deployment_id)

Skill: Debug with Logs

Build logs — Debug compilation/build failures:

GetBuildLogs(project_id, deployment_id, skip?)
// skip: number of lines to skip (for pagination)

Runtime logs — Debug application errors:

GetDeploymentLogs(project_id, deployment_id, since-seconds?)
// since-seconds: look back window (default: 60)

Environment logs — Aggregate logs for an environment:

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)

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)

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

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

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:

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

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)

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

Skill: Domain-Environment Assignment

Route domain traffic to specific environment:

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

ListDomains(project_id)

RefreshDomain(project_id, domain_id)

UpdateDomainEnvironment(project_id, domain_id, {environmentId})

DeleteDomain(project_id, domain_id)

GitHub Integration Skills

Skill: Connect GitHub Account

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

// 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:

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

Auto-promote — Automatically assign deployments to environment:

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

When

isAutoPromoteEnabled: true

Analytics & Monitoring Skills

Skill: Comprehensive Analytics

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

GetProjectEnvironmentAnalyticsOverallRequests

GetProjectEnvironmentAnalyticsRPM

GetProjectEnvironmentAnalyticsSuccessPercentage

GetProjectEnvironmentAnalyticsRequestsOverTime

GetProjectEnvironmentAnalyticsTopHitPaths

GetProjectEnvironmentAnalyticsTopErrorPaths

GetEnvAnalyticsReqDistribution

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:

UpdateProject(project_id, {
  "enabledSecurityScan": true
})

Trigger scan:

TriggerSecurityScan(project_id, deployment_id)

View results:

GetSecurityScan(project_id, deployment_id)
// Returns: {status, vulnerabilities, summary}

Download full report:

GetSecurityScanDownloadUri(project_id, deployment_id)
// Only when status is "successful"
// Returns signed URL for report download

Retry failed scan:

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.

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

Skill: Manage App Contents

// 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

ListApps()

UpdateApp(app_id, {name, description?, color?})

DeleteApp(app_id)

Note: Deleting an app sets

appId: null

API Key Management Skills

Skill: Create API Keys

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

ListAPIKeys()

UpdateAPIKey(api_key_id, {name, description?})

RevokeAPIKey(api_key_id)

CheckAPIKeyUniqueName({uniqueName})

Skill: User & Quota Management

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

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

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

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

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 ──┘

// 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

// 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

GetBuildLogs

GetDeploymentLogs

port

GetQuotas

WakeupDeployment

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

^[a-zA-Z0-9-]+$

^[a-zA-Z0-9 _-]+$

^[a-zA-Z0-9-]+$

^[a-zA-Z0-9 _-]+$

^[a-zA-Z0-9-]+$

Last updated: January 2025