When to use this skill

Use this skill for CloudBase Run backend service development when you need:

• •Long connection capabilities: WebSocket / SSE / server push
• •Long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
• •Custom runtime environments/system dependencies: custom images, specific system libraries
• •Multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
• •Stable external services with elastic scaling: pay-as-you-go, can scale down to 0
• •Private/internal network access: VPC/PRIVATE access, mini-program callContainer internal direct connection
• •AI agent development: develop personalized AI applications based on Function mode CloudRun

Do NOT use for:

• •Simple cloud functions (use cloud function development instead)
• •Frontend-only applications
• •Database schema design (use data-model-creation skill)

How to use this skill (for a coding agent)

1. •

   Choose the right mode

   • •Function mode: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000, local running supported
   • •Container mode: Any language and runtime, requires Dockerfile, local running not supported by tools
2. •

   Follow mandatory requirements

   • •Must listen on PORT environment variable (real port in container)
   • •Stateless service: write data externally (DB/storage/cache)
   • •No background persistent threads/processes outside requests
   • •Minimize dependencies, slim images; reduce cold start and deployment time
   • •Resource constraints: Mem = 2 × CPU (e.g., 0.25 vCPU → 0.5 GB)
   • •Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network
3. •

   Use tools correctly

   • •Read operations: queryCloudRun (list, detail, templates)
   • •Write operations: manageCloudRun (init, download, run, deploy, delete, createAgent)
   • •Always use absolute paths for targetPath
   • •Use force: true for delete operations
4. •

   Follow the workflow

   • •Initialize project → Check/generate Dockerfile (for container mode) → Local run (function mode only) → Configure access → Deploy → Verify

CloudBase Run AI Development Rules

A concise guide for AI assistants and engineering collaboration, providing "when to use, how to use" rules and tool workflows.

1. When to use CloudBase Run (Use Cases)

• •Need long connection capabilities: WebSocket / SSE / server push
• •Need long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
• •Need custom runtime environments/system dependencies: custom images, specific system libraries
• •Use multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
• •Need stable external services with elastic scaling: pay-as-you-go, can scale down to 0
• •Need private/internal network access: VPC/PRIVATE access, mini-program callContainer internal direct connection
• •Need to develop AI agents: develop personalized AI applications based on Function mode CloudRun

2. Mode Selection (Quick Comparison)

• •Function mode: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000; local running supported by tools
• •Container mode: Any language and runtime, requires Dockerfile; local running not supported by tools

Mode Comparison Checklist

3. Development Requirements (Must Meet)

• •Must listen on PORT environment variable (real port in container)
• •Stateless service: write data externally (DB/storage/cache)
• •No background persistent threads/processes outside requests
• •Minimize dependencies, slim images; reduce cold start and deployment time
• •Resource constraints: Mem = 2 × CPU (e.g., 0.25 vCPU → 0.5 GB)
• •Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network

4. Tools (Plain Language & Read/Write Separation)

• •Read operations (queryCloudRun):
  • •list: What services do I have? Can filter by name/type
  • •detail: Current configuration, version, access address of a service
  • •templates: Ready-to-use starter templates
• •Write operations (manageCloudRun):
  • •init: Create local project (optional template)
  • •download: Pull existing service code to local
  • •run: Run locally (Function mode only, supports normal function and Agent mode)
  • •deploy: Deploy local code to CloudRun
  • •delete: Delete service (requires explicit confirmation)
  • •createAgent: Create AI agent (based on Function mode CloudRun)
• •Important parameters (remember these):
  • •targetPath: Local directory (must be absolute path)
  • •serverConfig: Deployment parameters (CPU/Mem/instance count/access type/environment variables, etc.)
  • •runOptions: Local running port and temporary environment variables (Function mode), supports runMode: 'normal' | 'agent'
  • •agentConfig: Agent configuration (agentName, botTag, description, template)
  • •Delete must include force: true, otherwise it won't execute

5. Core Workflow (Understand Steps First, Then Examples)

1. •

   Choose mode

   • •Need multi-language/existing container/Docker: choose "Container mode"
   • •Need long connection/streaming/low latency/multiple functions coexisting: prioritize "Function mode"
2. •

   Initialize local project

   • •General: Use template init (both Function mode and Container mode can start from templates)
   • •Container mode must "check or generate Dockerfile":
     • •Node.js minimal example:
       dockerfile

       FROM node:18-alpine
       WORKDIR /app
       COPY package*.json ./
       RUN npm ci --omit=dev
       COPY . .
       ENV NODE_ENV=production
       EXPOSE 3000
       CMD ["node","server.js"]
       

     • •Python minimal example:
       dockerfile

       FROM python:3.11-slim
       WORKDIR /app
       COPY requirements.txt ./
       RUN pip install -r requirements.txt --no-cache-dir
       COPY . .
       ENV PORT=3000
       EXPOSE 3000
       CMD ["python","app.py"]
       

3. •

   Local running (Function mode only)

   • •Automatically use npm run dev/start or entry file via run
4. •

   Configure access

   • •Set OpenAccessTypes (WEB/VPC/PRIVATE) as needed; configure security domain and authentication for Web scenarios
5. •

   Deploy

   • •Specify CPU/Mem/instance count/environment variables, etc. during deploy
6. •

   Verify

   • •Use detail to confirm access address and configuration meet expectations

Example Tool Calls

1. •View templates/services

{ "name": "queryCloudRun", "arguments": { "action": "templates" } }

{ "name": "queryCloudRun", "arguments": { "action": "detail", "detailServerName": "my-svc" } }

1. •Initialize project

{ "name": "manageCloudRun", "arguments": { "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "template": "helloworld" } }

1. •Download code (optional)

{ "name": "manageCloudRun", "arguments": { "action": "download", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" } }

1. •Local running (Function mode only)

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } } }

1. •Deploy

{ "name": "manageCloudRun", "arguments": { "action": "deploy", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "serverConfig": { "OpenAccessTypes": ["WEB"], "Cpu": 0.5, "Mem": 1, "MinNum": 0, "MaxNum": 5 } } }

1. •Create AI agent (optional)

{ "name": "manageCloudRun", "arguments": { "action": "createAgent", "serverName": "my-agent", "targetPath": "/abs/ws/agents", "agentConfig": { "agentName": "MyAgent", "botTag": "demo", "description": "My agent", "template": "blank" } } }

1. •Run agent (optional)

{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-agent", "targetPath": "/abs/ws/agents/my-agent", "runOptions": { "port": 3000, "runMode": "agent" } } }

6. Best Practices (Strongly Recommended)

• •Prioritize PRIVATE/VPC or mini-program internal callContainer, reduce public network exposure
• •Web must use CloudBase Web SDK authentication; mini-programs authenticated by platform
• •Secrets via environment variables; separate configuration for multiple environments (dev/stg/prod)
• •Use queryCloudRun.detail to verify configuration and accessibility before and after deployment
• •Image layers reusable, small volume; monitor startup latency and memory usage
• •Agent development: Use @cloudbase/aiagent-framework, supports SSE streaming responses, BotId format is ibot-{name}-{tag}

7. Quick Troubleshooting

• •Access failure: Check OpenAccessTypes/domain/port, whether instance scaled down to 0
• •Deployment failure: Verify Dockerfile/build logs/image volume and CPU/Mem ratio
• •Local running failure: Only Function mode supported; requires package.json dev/start or entry index.js|app.js|server.js
• •Performance jitter: Reduce dependencies and initialization; appropriately increase MinNum; optimize cold start
• •Agent running failure: Check @cloudbase/aiagent-framework dependency, BotId format, SSE response format

8. Function Mode CloudRun (Function Mode) Key Points (Concise)

• •Definition: CloudRun + function framework (@cloudbase/functions-framework) + function code, making container service development as simple as writing cloud functions
• •When to choose: Need WebSocket/SSE/file upload/streaming responses; need long tasks or connect to DB/message queue; need multiple functions per instance and shared memory, low latency and better logs/debugging
• •Agent mode: Develop AI agents based on Function mode CloudRun, use @cloudbase/aiagent-framework, supports SSE streaming responses and personalized AI applications
• •Tool support: Local running only supports Function mode (manageCloudRun → run); deploy using manageCloudRun → deploy; query using queryCloudRun
• •Migration tips: Different from cloud function call chain/runtime, migration requires minor modifications (including client calling methods)
• •Portability: Based on function framework, can run locally/host/Docker, non-CloudRun requires self-managed build and deployment

9. Service Invocation Methods (Concise Examples)

HTTP Direct Access (when WEB public network enabled)

curl -L "https://<your-service-domain>"

WeChat Mini Program (internal direct connection, recommend closing public network)

// app.js (ensure wx.cloud.init() is called)
const res = await wx.cloud.callContainer({
  config: { env: "<envId>" },
  path: "/",
  method: "GET",
  header: { "X-WX-SERVICE": "<serviceName>" }
});

Web (JS SDK, need to configure security domain and authentication)

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({ env: "<envId>" });  // Collect user's phone number into variable `phoneNum` by providing a input UI

const auth = app.auth();

// Send SMS code
const verificationInfo = await auth.getVerification({
  phone_number: `+86 ${phoneNum}`,
});

// Collect user's phone number into variable `verificationCode` by providing a input UI 

// Sign in
await auth.signInWithSms({
  verificationInfo,
  verificationCode,
  phoneNum,
});

const res = await app.callContainer({
  name: "<serviceName>", method: "POST", path: "/api",
  header: { "Content-Type": "application/json" },
  data: { key: "value" }
});

// Web JS SDK initialization MUST be synchronous: // - Always use top-level import cloudbase from "@cloudbase/js-sdk"; // - Do NOT use dynamic imports like import("@cloudbase/js-sdk") or async wrappers such as initCloudBase() with internal initPromise

Node.js (server-side/cloud function internal call)

import tcb from "@cloudbase/node-sdk";
const app = tcb.init({});
const res = await app.callContainer({
  name: "<serviceName>", method: "GET", path: "/health",
  timeout: 5000
});

Recommendations

• •Mini Program/Server side prioritize internal network (VPC/PRIVATE) calls, reduce exposure surface
• •Web scenarios need to enable WEB, public domain and security domain, and use SDK authentication