Cloudrun Development

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:

       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:

       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" } }

2. Initialize project

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

3. Download code (optional)

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

4. Local running (Function mode only)

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

5. 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 } } }

6. 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" } } }

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