Standalone Install Note
If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.
- CloudBase main entry:
https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
- Current skill raw source:
https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudrun-development/SKILL.md
Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.
CloudBase Run Development
Activation Contract
Use this first when
- The task is to initialize, run, deploy, inspect, or debug a CloudBase Run service.
- The request needs a long-lived HTTP service, SSE, WebSocket, custom system dependencies, or container-style deployment.
- The task is to create or run an Agent service on CloudBase Run.
Read before writing code if
- You still need to choose between Function mode and Container mode.
- The prompt mentions
queryCloudRun, manageCloudRun, Dockerfile, service domains, or public/private access.
Then also read
- Cloud functions instead of CloudRun ->
../cloud-functions/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md)
- Agent SDK and AG-UI specifics ->
../cloudbase-agent/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-agent/SKILL.md)
- Web authentication for browser callers ->
../auth-web/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md)
Do NOT use for
- Simple Event Function or HTTP Function workflows that fit the function model better.
- Frontend-only projects with no backend service.
- Database-schema design tasks.
Common mistakes / gotchas
- Choosing CloudRun when the request only needs a normal cloud function.
- Forgetting to listen on the platform-provided
PORT.
- Treating CloudRun as stateful app hosting and storing important state on local disk.
- Assuming local run is available for Container mode.
- Opening public access by default when the scenario only needs private or mini-program internal access.
Minimal checklist
- Choose Function mode or Container mode explicitly.
- Confirm whether the service should be public, VPC-only, or mini-program internal.
- Keep the service stateless and externalize durable data.
- Use absolute paths for every local project path.
Overview
Use CloudBase Run when the task needs a deployed backend service rather than a short-lived serverless function.
When CloudRun is a better fit
- Long connections: WebSocket, SSE, server push
- Long-running request handling or persistent service processes
- Custom runtime environments or system libraries
- Arbitrary languages or frameworks
- Stable external service endpoints with elastic scaling
- AI Agent deployment on Function mode CloudRun
Mode selection
| Dimension |
Function mode |
Container mode |
| Best for |
Fast start, Node.js service patterns, built-in framework, Agent flows |
Existing containers, arbitrary runtimes, custom system dependencies |
| Port model |
Framework-managed local mode, deployed service still follows platform rules |
App must listen on injected PORT |
| Dockerfile |
Not required |
Required |
| Local run through tools |
Supported |
Not supported |
| Typical use |
Streaming APIs, low-latency backend, Agent service |
Custom language stack, migrated container app |
How to use this skill (for a coding agent)
Choose mode first
- Function mode -> quickest path for HTTP/SSE/WebSocket or Agent scenarios
- Container mode -> use when Docker/custom runtime is a real requirement
Follow mandatory runtime rules
- Listen on
PORT
- Keep the service stateless
- Put durable data in DB/storage/cache
- Keep dependencies and image size small
- Respect resource ratio guidance:
Mem = 2 × CPU
Use the correct tools
- Read operations ->
queryCloudRun
- Write operations ->
manageCloudRun
- Delete requires explicit confirmation and
force: true
- Always use absolute
targetPath
Follow the deployment sequence
- Initialize or download code
- For Container mode, verify Dockerfile
- Local run when available
- Configure access model
- Deploy and verify detail output
Tool routing
Read operations
queryCloudRun(action="list") -> list servicesqueryCloudRun(action="detail") -> inspect one service and its latest deploy status when availablequeryCloudRun(action="templates") -> see available startersqueryCloudRun(action="getDeployLog") -> retrieve the latest deploy log or a specified buildId
Write operations
manageCloudRun(action="init") -> create local projectmanageCloudRun(action="download") -> pull remote codemanageCloudRun(action="run") -> local run for Function modemanageCloudRun(action="deploy") -> deploy local projectmanageCloudRun(action="delete") -> delete servicemanageCloudRun(action="createAgent") -> create Agent service
Access guidance
- Web/public scenarios -> enable WEB access intentionally and pair it with the right auth flow.
- Mini Program -> prefer internal direct connection and avoid unnecessary public exposure.
- Private/VPC scenarios -> keep public access off unless the product requirement clearly needs it.
Quick examples
Initialize
{ "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" }
Local run (Function mode)
{ "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } }
Deploy
{
"action": "deploy",
"serverName": "my-svc",
"targetPath": "/abs/ws/my-svc",
"serverConfig": {
"OpenAccessTypes": ["PUBLIC"],
"Cpu": 0.5,
"Mem": 1,
"MinNum": 1,
"MaxNum": 5
}
}
Valid OpenAccessTypes values: OA (办公网访问), PUBLIC (公网访问), MINIAPP (小程序访问), VPC (VPC访问). Use PUBLIC for web applications that need public HTTPS access.
MinNum: 1 is the recommended default when you want to reduce cold-start latency. If the user explicitly prefers lower cost and accepts more cold starts, explain the tradeoff and let them reduce MinNum to 0.
Best practices
- Prefer PRIVATE/VPC or mini-program internal access when possible.
- Use environment variables for secrets and per-environment configuration.
- Verify configuration before and after deployment with
queryCloudRun(action="detail").
- Keep startup work small to reduce cold-start impact.
- For Agent scenarios, use the Agent SDK skill for protocol and adapter details instead of duplicating them here.
Troubleshooting hints
- Access failure -> check access type, domain setup, and whether the instance scaled to zero.
- Deployment failure -> inspect Dockerfile, build logs, and CPU/memory ratio.
- Local run failure -> remember only Function mode is supported by local-run tools.
- Performance issues -> reduce dependencies, optimize initialization, and tune minimum instances.
1---
2name: cloudrun-development
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.
4version: 2.23.8
5alwaysApply: false
6---
7
8## Standalone Install Note
9
10If this environment only installed the current skill, start from the CloudBase main entry and use the published `cloudbase/references/...` paths for sibling skills.
11
12- CloudBase main entry: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md`
13- Current skill raw source: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudrun-development/SKILL.md`
14
15Keep local `references/...` paths for files that ship with the current skill directory. When this file points to a sibling skill such as `auth-tool` or `web-development`, use the standalone fallback URL shown next to that reference.
16
17# CloudBase Run Development
18
19## Activation Contract
20
21### Use this first when
22
23- The task is to initialize, run, deploy, inspect, or debug a CloudBase Run service.
24- The request needs a long-lived HTTP service, SSE, WebSocket, custom system dependencies, or container-style deployment.
25- The task is to create or run an Agent service on CloudBase Run.
26
27### Read before writing code if
28
29- You still need to choose between Function mode and Container mode.
30- The prompt mentions `queryCloudRun`, `manageCloudRun`, Dockerfile, service domains, or public/private access.
31
32### Then also read
33
34- Cloud functions instead of CloudRun -> `../cloud-functions/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md`)
35- Agent SDK and AG-UI specifics -> `../cloudbase-agent/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudbase-agent/SKILL.md`)
36- Web authentication for browser callers -> `../auth-web/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-web/SKILL.md`)
37
38### Do NOT use for
39
40- Simple Event Function or HTTP Function workflows that fit the function model better.
41- Frontend-only projects with no backend service.
42- Database-schema design tasks.
43
44### Common mistakes / gotchas
45
46- Choosing CloudRun when the request only needs a normal cloud function.
47- Forgetting to listen on the platform-provided `PORT`.
48- Treating CloudRun as stateful app hosting and storing important state on local disk.
49- Assuming local run is available for Container mode.
50- Opening public access by default when the scenario only needs private or mini-program internal access.
51
52### Minimal checklist
53
54- Choose Function mode or Container mode explicitly.
55- Confirm whether the service should be public, VPC-only, or mini-program internal.
56- Keep the service stateless and externalize durable data.
57- Use absolute paths for every local project path.
58
59## Overview
60
61Use CloudBase Run when the task needs a deployed backend service rather than a short-lived serverless function.
62
63### When CloudRun is a better fit
64
65- Long connections: WebSocket, SSE, server push
66- Long-running request handling or persistent service processes
67- Custom runtime environments or system libraries
68- Arbitrary languages or frameworks
69- Stable external service endpoints with elastic scaling
70- AI Agent deployment on Function mode CloudRun
71
72## Mode selection
73
74| Dimension | Function mode | Container mode |
75| --- | --- | --- |
76| Best for | Fast start, Node.js service patterns, built-in framework, Agent flows | Existing containers, arbitrary runtimes, custom system dependencies |
77| Port model | Framework-managed local mode, deployed service still follows platform rules | App must listen on injected `PORT` |
78| Dockerfile | Not required | Required |
79| Local run through tools | Supported | Not supported |
80| Typical use | Streaming APIs, low-latency backend, Agent service | Custom language stack, migrated container app |
81
82## How to use this skill (for a coding agent)
83
841. **Choose mode first**
85 - Function mode -> quickest path for HTTP/SSE/WebSocket or Agent scenarios
86 - Container mode -> use when Docker/custom runtime is a real requirement
87
882. **Follow mandatory runtime rules**
89 - Listen on `PORT`
90 - Keep the service stateless
91 - Put durable data in DB/storage/cache
92 - Keep dependencies and image size small
93 - Respect resource ratio guidance: `Mem = 2 × CPU`
94
953. **Use the correct tools**
96 - Read operations -> `queryCloudRun`
97 - Write operations -> `manageCloudRun`
98 - Delete requires explicit confirmation and `force: true`
99 - Always use absolute `targetPath`
100
1014. **Follow the deployment sequence**
102 - Initialize or download code
103 - For Container mode, verify Dockerfile
104 - Local run when available
105 - Configure access model
106 - Deploy and verify detail output
107
108## Tool routing
109
110### Read operations
111
112- `queryCloudRun(action="list")` -> list services
113- `queryCloudRun(action="detail")` -> inspect one service and its latest deploy status when available
114- `queryCloudRun(action="templates")` -> see available starters
115- `queryCloudRun(action="getDeployLog")` -> retrieve the latest deploy log or a specified `buildId`
116
117### Write operations
118
119- `manageCloudRun(action="init")` -> create local project
120- `manageCloudRun(action="download")` -> pull remote code
121- `manageCloudRun(action="run")` -> local run for Function mode
122- `manageCloudRun(action="deploy")` -> deploy local project
123- `manageCloudRun(action="delete")` -> delete service
124- `manageCloudRun(action="createAgent")` -> create Agent service
125
126## Access guidance
127
128- **Web/public scenarios** -> enable WEB access intentionally and pair it with the right auth flow.
129- **Mini Program** -> prefer internal direct connection and avoid unnecessary public exposure.
130- **Private/VPC scenarios** -> keep public access off unless the product requirement clearly needs it.
131
132## Quick examples
133
134### Initialize
135
136```json
137{ "action": "init", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc" }
138```
139
140### Local run (Function mode)
141
142```json
143{ "action": "run", "serverName": "my-svc", "targetPath": "/abs/ws/my-svc", "runOptions": { "port": 3000 } }
144```
145
146### Deploy
147
148```json
149{
150 "action": "deploy",
151 "serverName": "my-svc",
152 "targetPath": "/abs/ws/my-svc",
153 "serverConfig": {
154 "OpenAccessTypes": ["PUBLIC"],
155 "Cpu": 0.5,
156 "Mem": 1,
157 "MinNum": 1,
158 "MaxNum": 5
159 }
160}
161```
162
163**Valid `OpenAccessTypes` values**: `OA` (办公网访问), `PUBLIC` (公网访问), `MINIAPP` (小程序访问), `VPC` (VPC访问). Use `PUBLIC` for web applications that need public HTTPS access.
164
165`MinNum: 1` is the recommended default when you want to reduce cold-start latency. If the user explicitly prefers lower cost and accepts more cold starts, explain the tradeoff and let them reduce `MinNum` to `0`.
166
167## Best practices
168
1691. Prefer PRIVATE/VPC or mini-program internal access when possible.
1702. Use environment variables for secrets and per-environment configuration.
1713. Verify configuration before and after deployment with `queryCloudRun(action="detail")`.
1724. Keep startup work small to reduce cold-start impact.
1735. For Agent scenarios, use the Agent SDK skill for protocol and adapter details instead of duplicating them here.
174
175## Troubleshooting hints
176
177- **Access failure** -> check access type, domain setup, and whether the instance scaled to zero.
178- **Deployment failure** -> inspect Dockerfile, build logs, and CPU/memory ratio.
179- **Local run failure** -> remember only Function mode is supported by local-run tools.
180- **Performance issues** -> reduce dependencies, optimize initialization, and tune minimum instances.
aiskillstore