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)
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
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
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
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
| Dimension |
Function Mode |
Container Mode |
| Language/Framework |
Node.js (via @cloudbase/functions-framework) |
Any language/runtime (Java/Go/PHP/.NET/Python/Node.js, etc.) |
| Runtime |
Function framework loads functions (Runtime) |
Docker image starts process |
| Port |
Fixed 3000 |
Application listens on PORT (injected by platform during deployment) |
| Dockerfile |
Not required |
Required (and must pass local build) |
| Local Running |
Supported (built-in tools) |
Not supported (recommend using Docker for debugging) |
| Typical Scenarios |
WebSocket/SSE/streaming responses, forms/files, low latency, multiple functions per instance, shared memory |
Arbitrary system dependencies/languages, migrating existing containerized applications |
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)
Choose mode
- Need multi-language/existing container/Docker: choose "Container mode"
- Need long connection/streaming/low latency/multiple functions coexisting: prioritize "Function mode"
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"]
Local running (Function mode only)
- Automatically use
npm run dev/start or entry file via run
Configure access
- Set
OpenAccessTypes (WEB/VPC/PRIVATE) as needed; configure security domain and authentication for Web scenarios
Deploy
- Specify CPU/Mem/instance count/environment variables, etc. during
deploy
Verify
- Use
detail to confirm access address and configuration meet expectations
Example Tool Calls
- View templates/services
{ "name": "queryCloudRun", "arguments": { "action": "templates" } }
{ "name": "queryCloudRun", "arguments": { "action": "detail", "detailServerName": "my-svc" } }
- Initialize project
{ "name": "manageCloudRun", "arguments": { "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "template": "helloworld" } }
- Download code (optional)
{ "name": "manageCloudRun", "arguments": { "action": "download", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" } }
- Local running (Function mode only)
{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } } }
- 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 } } }
- 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" } } }
- 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
1---
2name: cloudrun-development-2
3description: CloudBase Run backend development rules (Function mode/Container mode). Use this skill when deploying backend services that require long connections, multi-language support, custom environments, or AI agent development.
4alwaysApply: false
5metadata:
6 source: https://skillmd.com/skills/ahang1598/cloudrun-development-2
7---
8
9## When to use this skill
10
11Use this skill for **CloudBase Run backend service development** when you need:
12
13- Long connection capabilities: WebSocket / SSE / server push
14- Long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
15- Custom runtime environments/system dependencies: custom images, specific system libraries
16- Multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
17- Stable external services with elastic scaling: pay-as-you-go, can scale down to 0
18- Private/internal network access: VPC/PRIVATE access, mini-program `callContainer` internal direct connection
19- AI agent development: develop personalized AI applications based on Function mode CloudRun
20
21**Do NOT use for:**
22- Simple cloud functions (use cloud function development instead)
23- Frontend-only applications
24- Database schema design (use data-model-creation skill)
25
26---
27
28## How to use this skill (for a coding agent)
29
301. **Choose the right mode**
31 - **Function mode**: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000, local running supported
32 - **Container mode**: Any language and runtime, requires Dockerfile, local running not supported by tools
33
342. **Follow mandatory requirements**
35 - Must listen on `PORT` environment variable (real port in container)
36 - Stateless service: write data externally (DB/storage/cache)
37 - No background persistent threads/processes outside requests
38 - Minimize dependencies, slim images; reduce cold start and deployment time
39 - Resource constraints: `Mem = 2 × CPU` (e.g., 0.25 vCPU → 0.5 GB)
40 - Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network
41
423. **Use tools correctly**
43 - **Read operations**: `queryCloudRun` (list, detail, templates)
44 - **Write operations**: `manageCloudRun` (init, download, run, deploy, delete, createAgent)
45 - Always use absolute paths for `targetPath`
46 - Use `force: true` for delete operations
47
484. **Follow the workflow**
49 - Initialize project → Check/generate Dockerfile (for container mode) → Local run (function mode only) → Configure access → Deploy → Verify
50
51---
52
53# CloudBase Run AI Development Rules
54
55A concise guide for AI assistants and engineering collaboration, providing "when to use, how to use" rules and tool workflows.
56
57## 1. When to use CloudBase Run (Use Cases)
58
59- Need long connection capabilities: WebSocket / SSE / server push
60- Need long-running or persistent processes: tasks that are not suitable for cloud functions, background jobs
61- Need custom runtime environments/system dependencies: custom images, specific system libraries
62- Use multi-language/arbitrary frameworks: Java, Go, PHP, .NET, Python, Node.js, etc.
63- Need stable external services with elastic scaling: pay-as-you-go, can scale down to 0
64- Need private/internal network access: VPC/PRIVATE access, mini-program `callContainer` internal direct connection
65- Need to develop AI agents: develop personalized AI applications based on Function mode CloudRun
66
67## 2. Mode Selection (Quick Comparison)
68
69- **Function mode**: Fastest to get started, built-in HTTP/WebSocket/SSE, fixed port 3000; local running supported by tools
70- **Container mode**: Any language and runtime, requires Dockerfile; local running not supported by tools
71
72### Mode Comparison Checklist
73
74| Dimension | Function Mode | Container Mode |
75| --- | --- | --- |
76| Language/Framework | Node.js (via `@cloudbase/functions-framework`) | Any language/runtime (Java/Go/PHP/.NET/Python/Node.js, etc.) |
77| Runtime | Function framework loads functions (Runtime) | Docker image starts process |
78| Port | Fixed 3000 | Application listens on `PORT` (injected by platform during deployment) |
79| Dockerfile | Not required | Required (and must pass local build) |
80| Local Running | Supported (built-in tools) | Not supported (recommend using Docker for debugging) |
81| Typical Scenarios | WebSocket/SSE/streaming responses, forms/files, low latency, multiple functions per instance, shared memory | Arbitrary system dependencies/languages, migrating existing containerized applications |
82
83## 3. Development Requirements (Must Meet)
84
85- Must listen on `PORT` environment variable (real port in container)
86- Stateless service: write data externally (DB/storage/cache)
87- No background persistent threads/processes outside requests
88- Minimize dependencies, slim images; reduce cold start and deployment time
89- Resource constraints: `Mem = 2 × CPU` (e.g., 0.25 vCPU → 0.5 GB)
90- Access control: Only enable public network for Web scenarios; mini-programs prioritize internal direct connection, recommend closing public network
91
92## 4. Tools (Plain Language & Read/Write Separation)
93
94- **Read operations** (`queryCloudRun`):
95 - `list`: What services do I have? Can filter by name/type
96 - `detail`: Current configuration, version, access address of a service
97 - `templates`: Ready-to-use starter templates
98- **Write operations** (`manageCloudRun`):
99 - `init`: Create local project (optional template)
100 - `download`: Pull existing service code to local
101 - `run`: Run locally (Function mode only, supports normal function and Agent mode)
102 - `deploy`: Deploy local code to CloudRun
103 - `delete`: Delete service (requires explicit confirmation)
104 - `createAgent`: Create AI agent (based on Function mode CloudRun)
105- **Important parameters** (remember these):
106 - `targetPath`: Local directory (must be absolute path)
107 - `serverConfig`: Deployment parameters (CPU/Mem/instance count/access type/environment variables, etc.)
108 - `runOptions`: Local running port and temporary environment variables (Function mode), supports `runMode: 'normal' | 'agent'`
109 - `agentConfig`: Agent configuration (agentName, botTag, description, template)
110 - Delete must include `force: true`, otherwise it won't execute
111
112## 5. Core Workflow (Understand Steps First, Then Examples)
113
1141) **Choose mode**
115 - Need multi-language/existing container/Docker: choose "Container mode"
116 - Need long connection/streaming/low latency/multiple functions coexisting: prioritize "Function mode"
117
1182) **Initialize local project**
119 - General: Use template `init` (both Function mode and Container mode can start from templates)
120 - Container mode must "check or generate Dockerfile":
121 - Node.js minimal example:
122 ```dockerfile
123 FROM node:18-alpine
124 WORKDIR /app
125 COPY package*.json ./
126 RUN npm ci --omit=dev
127 COPY . .
128 ENV NODE_ENV=production
129 EXPOSE 3000
130 CMD ["node","server.js"]
131 ```
132 - Python minimal example:
133 ```dockerfile
134 FROM python:3.11-slim
135 WORKDIR /app
136 COPY requirements.txt ./
137 RUN pip install -r requirements.txt --no-cache-dir
138 COPY . .
139 ENV PORT=3000
140 EXPOSE 3000
141 CMD ["python","app.py"]
142 ```
143
1443) **Local running** (Function mode only)
145 - Automatically use `npm run dev/start` or entry file via `run`
146
1474) **Configure access**
148 - Set `OpenAccessTypes` (WEB/VPC/PRIVATE) as needed; configure security domain and authentication for Web scenarios
149
1505) **Deploy**
151 - Specify CPU/Mem/instance count/environment variables, etc. during `deploy`
152
1536) **Verify**
154 - Use `detail` to confirm access address and configuration meet expectations
155
156### Example Tool Calls
157
1581) **View templates/services**
159```json
160{ "name": "queryCloudRun", "arguments": { "action": "templates" } }
161```
162```json
163{ "name": "queryCloudRun", "arguments": { "action": "detail", "detailServerName": "my-svc" } }
164```
165
1662) **Initialize project**
167```json
168{ "name": "manageCloudRun", "arguments": { "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "template": "helloworld" } }
169```
170
1713) **Download code** (optional)
172```json
173{ "name": "manageCloudRun", "arguments": { "action": "download", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" } }
174```
175
1764) **Local running** (Function mode only)
177```json
178{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } } }
179```
180
1815) **Deploy**
182```json
183{ "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 } } }
184```
185
1866) **Create AI agent** (optional)
187```json
188{ "name": "manageCloudRun", "arguments": { "action": "createAgent", "serverName": "my-agent", "targetPath": "/abs/ws/agents", "agentConfig": { "agentName": "MyAgent", "botTag": "demo", "description": "My agent", "template": "blank" } } }
189```
190
1917) **Run agent** (optional)
192```json
193{ "name": "manageCloudRun", "arguments": { "action": "run", "serverName": "my-agent", "targetPath": "/abs/ws/agents/my-agent", "runOptions": { "port": 3000, "runMode": "agent" } } }
194```
195
196## 6. Best Practices (Strongly Recommended)
197
198- Prioritize PRIVATE/VPC or mini-program internal `callContainer`, reduce public network exposure
199- Web must use CloudBase Web SDK authentication; mini-programs authenticated by platform
200- Secrets via environment variables; separate configuration for multiple environments (dev/stg/prod)
201- Use `queryCloudRun.detail` to verify configuration and accessibility before and after deployment
202- Image layers reusable, small volume; monitor startup latency and memory usage
203- Agent development: Use `@cloudbase/aiagent-framework`, supports SSE streaming responses, BotId format is `ibot-{name}-{tag}`
204
205## 7. Quick Troubleshooting
206
207- **Access failure**: Check OpenAccessTypes/domain/port, whether instance scaled down to 0
208- **Deployment failure**: Verify Dockerfile/build logs/image volume and CPU/Mem ratio
209- **Local running failure**: Only Function mode supported; requires `package.json` `dev`/`start` or entry `index.js|app.js|server.js`
210- **Performance jitter**: Reduce dependencies and initialization; appropriately increase MinNum; optimize cold start
211- **Agent running failure**: Check `@cloudbase/aiagent-framework` dependency, BotId format, SSE response format
212
213## 8. Function Mode CloudRun (Function Mode) Key Points (Concise)
214
215- **Definition**: CloudRun + function framework (`@cloudbase/functions-framework`) + function code, making container service development as simple as writing cloud functions
216- **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
217- **Agent mode**: Develop AI agents based on Function mode CloudRun, use `@cloudbase/aiagent-framework`, supports SSE streaming responses and personalized AI applications
218- **Tool support**: Local running only supports Function mode (`manageCloudRun` → `run`); deploy using `manageCloudRun` → `deploy`; query using `queryCloudRun`
219- **Migration tips**: Different from cloud function call chain/runtime, migration requires minor modifications (including client calling methods)
220- **Portability**: Based on function framework, can run locally/host/Docker, non-CloudRun requires self-managed build and deployment
221
222## 9. Service Invocation Methods (Concise Examples)
223
224### HTTP Direct Access (when WEB public network enabled)
225```bash
226curl -L "https://<your-service-domain>"
227```
228
229### WeChat Mini Program (internal direct connection, recommend closing public network)
230```js
231// app.js (ensure wx.cloud.init() is called)
232const res = await wx.cloud.callContainer({
233 config: { env: "<envId>" },
234 path: "/",
235 method: "GET",
236 header: { "X-WX-SERVICE": "<serviceName>" }
237});
238```
239
240### Web (JS SDK, need to configure security domain and authentication)
241```js
242import cloudbase from "@cloudbase/js-sdk";
243
244const app = cloudbase.init({ env: "<envId>" }); // Collect user's phone number into variable `phoneNum` by providing a input UI
245
246const auth = app.auth();
247
248// Send SMS code
249const verificationInfo = await auth.getVerification({
250 phone_number: `+86 ${phoneNum}`,
251});
252
253// Collect user's phone number into variable `verificationCode` by providing a input UI
254
255// Sign in
256await auth.signInWithSms({
257 verificationInfo,
258 verificationCode,
259 phoneNum,
260});
261
262const res = await app.callContainer({
263 name: "<serviceName>", method: "POST", path: "/api",
264 header: { "Content-Type": "application/json" },
265 data: { key: "value" }
266});
267```
268
269// Web JS SDK initialization MUST be synchronous:
270// - Always use top-level `import cloudbase from "@cloudbase/js-sdk";`
271// - Do NOT use dynamic imports like `import("@cloudbase/js-sdk")` or async wrappers such as `initCloudBase()` with internal `initPromise`
272
273### Node.js (server-side/cloud function internal call)
274```js
275import tcb from "@cloudbase/node-sdk";
276const app = tcb.init({});
277const res = await app.callContainer({
278 name: "<serviceName>", method: "GET", path: "/health",
279 timeout: 5000
280});
281```
282
283### Recommendations
284- Mini Program/Server side prioritize internal network (VPC/PRIVATE) calls, reduce exposure surface
285- Web scenarios need to enable WEB, public domain and security domain, and use SDK authentication