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

@cloudbase/functions-framework

PORT

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>" });
await app.auth().toDefaultLoginPage({});
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";

import("@cloudbase/js-sdk")

initCloudBase()

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