cloudrun-development
Deploys and manages backend services on CloudBase using either Function or Container modes with support for HTTP, WebSockets, and custom dependencies.
Install
mkdir -p .claude/skills/cloudrun-development && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/2417" && unzip -o skill.zip -d .claude/skills/cloudrun-development && rm skill.zipInstalls to .claude/skills/cloudrun-development
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →Deploys containerized backend services
- →Configures long-lived HTTP and WebSocket endpoints
- →Initializes custom system dependencies in Dockerfiles
- →Manages service domains and public/private access
- →Sets up AI agent hosting environments
How it works
It automates the construction of deployment manifests and environment settings required to run long-running container processes on the CloudBase infrastructure.
Inputs & outputs
When to use cloudrun-development
- →Deploy a containerized backend service
- →Debug a CloudBase Run service domain
- →Initialize an AI agent service
- →Configure long-lived HTTP or WebSocket connections
About this skill
Sibling skills (local only)
Sibling CloudBase skills ship beside this skill. Use local relative paths such as ../auth-tool-cloudbase/SKILL.md.
If a referenced sibling skill file is missing from this environment, ask the user to install the full CloudBase plugin (or the missing skill). Do not HTTP-fetch remote skill or protocol markdown into the agent context.
Cross-cutting protocols (required before writing HTTP handlers or deploying images):
- Sensitive Runtime Data Protection:
../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md - Deployment Gate:
../cloudbase-platform/references/protocols/deployment-gate.md
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.
- The task migrates an existing / GitHub / third-party backend that uses classic
DATABASE_URL/ TCP database clients. - The service requires a stable independent process (long connections, custom runtime, VPC database access) — see the 「云托管 vs HTTP 云函数」 decision section below. A Dockerfile alone is not a strong trigger.
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. - The app depends on MySQL, PostgreSQL, Redis, or other VPC-private resources over TCP → 先做数据库访问方式决策(SDK/网关优先,见下方「数据库访问方式决策门」);确认必须 TCP 直连后 → also read
references/vpc-and-database.md. - You are choosing between CloudRun and HTTP cloud functions for a stateless HTTP service.
- The service calls CloudBase resources (PG
app.rdb(), NoSQL, storage, functions) through an SDK → 先过「计算资源访问 CloudBase 的凭证决策门」:凭证谁签发、怎么注入、怎么吊销,都必须在写代码之前定下来。 - Container deploy fails (
deploy_failed, Pod not ready, readiness/probe failed, third-partyimageUrlwon't stay up) → also readreferences/image-deploy-troubleshooting.mdand follow the Container deploy failure SOP below. Do not start by raisingInitialDelaySeconds.
Then also read
- Cloud functions instead of CloudRun ->
../cloud-functions/SKILL.md - Agent SDK and AG-UI specifics ->
../cloudbase-agent/SKILL.md - Web authentication for browser callers ->
../auth-web-cloudbase/SKILL.md - Existing app + TCP database networking ->
references/vpc-and-database.md - Container image deploy failure / probe /
deploy_failed->references/image-deploy-troubleshooting.md - Service calls CloudBase resources through an SDK (credential source / injection / revocation) ->
../cloud-functions/references/http-function-credentials.md - Billing questions about a CloudRun charge ("why was I charged when nothing was deployed", "the free quota wasn't used up") ->
../cloud-api-operations/references/recipes/billing-charges-explained.md(the gifted quota is a 3-month total, and a container bills while instance count is not 0)
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
PORTin Container mode — and its mirror image in Function mode: callingapp.listen()there, where the framework already owns the port and the second bind dies withEADDRINUSE. - Guessing the credential environment variable name.
@cloudbase/node-sdkreadsCLOUDBASE_APIKEY; an invented name (for exampleTCB_API_KEY) is silently ignored and only shows up later as "no credentials at runtime". - Copying a server credential out of the local client login state (
auth.json,.cloudbase/) and injecting it into a deployed service. Issue the key withmanageAppAuth(action="createApiKey", keyType="api_key")instead, so it has an owner, a rotation path, and akeyIdyou can revoke. See../cloud-functions/references/http-function-credentials.md. - Baking static content into the image — media files, user uploads, or assets that change on their own cadence. Three cases, one root cause: the image is rebuilt, re-pushed and re-pulled on every deploy and on every scale-up, so anything large or independently-changing makes every deploy slower for no reason.
- Media files (
*.mp4, large images, fonts) pulled in by aCOPY . .— one demo video can turn a 30-second deploy into a multi-minute one. Media belongs in cloud storage, referenced by URL. Add a.dockerignorecovering*.mp4,*.mov,*.zip,*.psd, and media directories such aspublic/videos/. - User uploads written to the container filesystem — the service is stateless; anything on local disk is gone on the next deploy, restart, or scale-out. Uploads go to cloud storage.
- Frequently-updated static resources served from the image — if an asset changes on its own schedule, every change forces a full service redeploy. Serve it from cloud storage so the service only redeploys when the code changes.
- Media files (
- 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.
- Deploying an existing app with
DATABASE_URL/ MySQL / PostgreSQL / Redis but omittingserverConfig.VpcConf— deploy appears to succeed, then runtime DB connections fail. - 新应用部署默认选 TCP 直连数据库 — 能用 SDK/网关访问的数据(PG
app.rdb()、NoSQL、storage)不需要VpcConf也不需要数据库账号密码;仅迁移类应用(经典驱动/ORM 无法替换)才走 TCP 直连 +VpcConf。见「数据库访问方式决策门」。 - Confusing
OpenAccessTypes(how users reach the service) withVpcConf(how the service reaches VPC databases). - Deploying to an environment that has not initialized CloudRun —
CreateCloudRunServeron an environment with no 大租户 record silently lands in the legacy 小租户 path, creating wrong small-tenant services/versions. Always ensure the environment is initialized first (manageCloudRun(action="initEnv"), tcbr) before the first deploy.manageCloudRun(action="deploy")now blocks new-service creation on uninitialized environments with guidance. - Using the legacy
tcbCloudRun API (CreateCloudBaseRunResource/DescribeCloudBaseRunResource/DeleteCloudBaseRunResource) — these are deprecated 小租户 open APIs and are blocked incallCloudApi. CloudRun always goes throughtcbr(CreateCloudRunEnv/CreateCloudRunServer). Query a single environment's base info / whether CloudRun is enabled withDescribeEnvBaseInfo(EnvIdrequired) — usemanageCloudRun(action="initEnv")to open andqueryCloudRun(action="envStatus")to poll status; query the environment list / resource info withDescribeCloudRunEnvs(EnvIdoptional filter). - Deploying
httpbin/ request-echo images or returningreq.headers/process.env— CloudBase may injectx-cloudbase-context(base64 temporary credentials). Echoing it leaks account cloud access. Follow../cloudbase-platform/references/protocols/sensitive-runtime-data-protection.md. - Seeing readiness probe failed /
deploy_failedand immediately raisingInitialDelaySeconds— the probe window is already ~N+150s; crash loops and loopback binds are not slow-start. Follow the Container deploy failure SOP. - Deploying a third-party image without reading its run docs — missing
Cmd, bind-address env, orVolumesConflooks identical to a probe failure. - Calling
getDeployLogforimageUrldeploys — that is CODING build log; usegetProcessLog. - Treating startup banners as proof the service is healthy — pull
getProcessLogtwice and compare; a repeated boot sequence is a restart loop.
Minimal checklist
- Choose Function mode or Container mode explicitly.
- Confirm the environment has CloudRun initialized before the first deploy — a brand-new environment must call
CreateCloudRunEnv(tcbr) first; neverCreateCloudRunServeron an uninitialized environment (it falls back to the legacy 小租户 path).manageCloudRun(action="deploy")validates this automatically and blocks new services on uninitialized environments. When blocked, first callmanageCloudRun(action="initEnv", envId=...)(异步开通) and pollqueryCloudRun(action="envStatus")untilStatus=normal, or reconsider an HTTP cloud function to bypass CloudRun entirely. - Confirm whether the service should be public, VPC-only, or mini-program internal (ingress).
- If the app uses TCP databases/caches, resolve and set
VpcConf(egress / private network) before deploy — seereferences/vpc-and-database.md. - Keep the service stateless and externalize durable data.
- Separate static from dynamic: media files, user uploads, and frequently-updated assets live in cloud storage, not in the image. Check what the Dockerfile copies in.
- Settle the credential path for every CloudBase SDK call before writing code — a server API Key issued through
manageAppAuth(action="createApiKey")and injected viaEnvParams, never a key copied out of the local client login state. - Use absolute paths for every local project path.
- Confirm handlers never echo
x-cloudbase-context, full headers, or credential env vars; do not deploy httpbin-style reflectors. - For third-party images, complete the five-item docs checklist (Cmd / port / bind env / volume / health) before deploy.
Overview
Use CloudBase Run when the task needs a deployed backend service rather than a short-lived serverless function.
云托管 vs HTTP 云函数(按需求选,不按文件选)
核心原则:HTTP 云函数优先。只有需求真正需要云托管时才用云托管;有
Dockerfile不等于必须上云托管。
HTTP 云函数更合适(优先):
- 无状态 HTTP 服务,监听
PORT/9000,只做「请求进来 → 处理 →
Content truncated.
When not to use it
- →Deploying simple static frontend sites
- →Serverless functions with short execution timeouts
Prerequisites
Limitations
- →Requires containerization knowledge
- →Limited by the CloudBase service plan
How it compares
It provides tailored configurations for non-standard services like WebSockets that differ from traditional short-lived serverless functions.
Compared to similar skills
cloudrun-development side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| cloudrun-development (this skill) | 1 | 5mo | No flags | Advanced |
| hosted-agents-v2-py | 0 | 7mo | Review | Intermediate |
| ideogram-deploy-integration | 1 | 4mo | Caution | Intermediate |
| deepgram-deploy-integration | 1 | 4mo | Caution | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by TencentCloudBase
View all by TencentCloudBase →You might also like
hosted-agents-v2-py
wegonbeok45
Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.
ideogram-deploy-integration
jeremylongshore
Deploy Ideogram integrations to Vercel, Fly.io, and Cloud Run platforms. Use when deploying Ideogram-powered applications to production, configuring platform-specific secrets, or setting up deployment pipelines. Trigger with phrases like "deploy ideogram", "ideogram Vercel", "ideogram production deploy", "ideogram Cloud Run", "ideogram Fly.io".
deepgram-deploy-integration
jeremylongshore
Deploy Deepgram integrations to production environments. Use when deploying to cloud platforms, configuring production infrastructure, or setting up Deepgram in containerized environments. Trigger with phrases like "deploy deepgram", "deepgram docker", "deepgram kubernetes", "deepgram production deploy", "deepgram cloud".
aspire
davidortinau
**WORKFLOW SKILL** - Orchestrates Aspire applications using the Aspire CLI and MCP tools for running, debugging, deploying, and managing distributed apps. USE FOR: aspire run, aspire stop, aspire deploy, start aspire app, aspire describe, list aspire integrations, debug aspire issues, view aspire lo
gcp-cloud-run
mk-knight23
Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-driven architecture with Pub/Sub.
gcp-cloud-run
aj-geddes
Deploy containerized applications on Google Cloud Run with automatic scaling, traffic management, and service mesh integration. Use for container-based serverless computing.