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