Byteplus cloud

BytePlus Cloud

Operate BytePlus from a coding-agent workspace. Treat this skill as an orchestration and safety layer over current official tools, not as a frozen API catalog.

Resolve <skill-dir> to the directory containing this file.

Apply the operating contract

1. Retrieve before relying on memory. Confirm current flags, action names, schemas, regions, limits, quotas, pricing, and product availability from live official sources.
2. Use only the capability currently exposed by an official CLI, provider schema, SDK, API, or product MCP. Never infer that a console control is programmable.
3. Establish the exact BytePlus profile, account identity, region, project, and environment before any remote mutation. Never silently use an ambient production target.
4. Inspect current resources before proposing changes. Prefer reuse or import over duplicate creation.
5. Separate planning from execution. Show the target, current state, changes, cost/security effects, verification, and rollback before consequential operations.
6. Keep credentials out of prompts, source files, manifests, command arguments, logs, and tool output. Never print ~/.byteplus/config.json, ~/.nest.json, or secret-bearing environment variables.
7. Verify every mutation through a fresh read, health probe, or product status check. Do not treat a successful command exit as proof that the application works.
8. Leave reproducible state: prefer Terraform for persistent multi-resource infrastructure and record non-secret resource mappings for imperative deployments.
9. Prefer agent-executable interfaces over console instructions. Never send the developer to the console for an operation exposed by a verified CLI, provider, SDK, or API. If a documented UI-only prerequisite remains, such as product activation, terms, billing setup, or service-role consent, identify the single minimal step and resume the automated workflow afterward.

Load only the required references

• Read sources.md before using exact API, schema, limit, price, region, or installation claims.
• Read services.md when selecting products or checking whether bp, Terraform, nest, an SDK, or an MCP is the right interface.
• Read cli.md before installing, authenticating, discovering, or invoking bp.
• Read iac.md before creating or changing Terraform/OpenTofu configuration.
• Read edge-functions.md before using nest or the official Edge Functions MCP.
• Read vefaas-functions.md before creating, releasing, invoking, exposing, troubleshooting, or deleting Function Service event functions and web applications.
• Read cloud-sandbox.md before creating a veFaaS sandbox application or instance, executing a sandbox workload, handling a WebShell endpoint, or cleaning up sandbox resources.
• Read ecs-vpc.md for VM, network, security-group, load-balancer, private-deployment, and bounded end-to-end ECS-over-SSH work.
• Read databases.md before provisioning or connecting to managed MySQL, PostgreSQL, or SQL Server.
• Read service-readiness.md before the first create for Kafka, KMS, or another activation/cross-service-role-dependent managed service, and when a schema-correct create returns an opaque 400 or 500.
• Read vke.md for Kubernetes and Container Registry deployments.
• Read modelark.md for endpoint lifecycle, Seed text, Seedream image, or Seedance video integration and bounded smoke tests.
• Read seed-speech.md for text-to-speech activation, application credentials, resource selection, generation, and verification.
• Read tos.md for buckets and objects; TOS is not available through the verified bp/Cloud Control baseline.
• Read observability.md for logs, metrics, alarms, VMP, and post-deployment diagnosis.
• Read agentkit.md only when building or operating an AgentKit application.
• Read operations.md for deployment, verification, troubleshooting, rollback, cleanup, and project-manifest workflows.
• Read security.md before any remote mutation, IAM/networking change, public exposure, billable resource, secret operation, or deletion.

Follow the end-to-end workflow

1. Classify the request

Distinguish among:

• architecture or documentation advice;
• read-only account inspection;
• local application changes;
• infrastructure planning;
• remote provisioning or deployment;
• troubleshooting;
• rollback or deletion.

Do not mutate remote state for a review, explanation, audit, or diagnosis-only request.

2. Inspect the workspace

Identify the runtime, framework, ports, build command, health endpoint, data stores, secrets, network requirements, traffic pattern, availability target, and existing IaC. Preserve the user's current deployment conventions when they are sound.

Check for existing BytePlus artifacts such as Terraform files, nest.json, deployment scripts, CI workflows, SDK configuration, and a byteplus.project.yaml manifest. Never overwrite an existing manifest or IaC layout without understanding it.

3. Diagnose the local toolchain

Run the local read-only doctor:

python3 <skill-dir>/scripts/byteplus_doctor.py --json

Add --profile NAME --region REGION --check-auth only when an authenticated identity check is needed. The doctor redacts credential-like fields. The STS call does not mutate cloud resources, but bp may refresh and cache temporary OAuth/SSO credentials as part of normal authentication.

Resolve the operational CLI only with command -v bp. A binary under /tmp, /private/tmp, another OS temporary directory, or a test/build staging directory is only a validation artifact; never reuse or report it as the developer's installed bp.

If bp is missing and the requested task needs account inspection, provisioning, deployment, or troubleshooting, inspect a verified persistent installation plan:

python3 <skill-dir>/scripts/install_bp.py --dry-run --dest "$HOME/.local/bin"

Then follow one of these branches instead of silently continuing with a temporary binary:

• If the user already authorized installing the skill's required local tooling, install the exact version from the reviewed plan into the persistent user directory. Prefer an independently obtained --sha256 pin. Without one, disclose that the official archive and checksum share one trust channel and use --trust-official-release only within the user's installation authorization.
• Otherwise, pause the operational workflow and ask whether the verified BytePlus CLI may be installed at $HOME/.local/bin/bp. Show the destination and source; do not make the user infer what prerequisite is missing.
• If the request is explicitly planning/documentation-only or forbids local installation, do not install. State that bp is unavailable and give the exact persistent install command as the next step.

The installer permits latest only for dry-run discovery. An actual installation requires an exact version plus either an independently obtained digest or explicit acceptance of the official-release trust channel. It verifies the published SHA-256 checksum and does not execute the downloaded binary. After installation, run $HOME/.local/bin/bp version. If that directory is not on PATH, use the persistent absolute path for the current task and tell the user how to add it; do not edit shell startup files without permission.

4. Establish the target

Require or discover all of:

• profile name and authentication mode;
• account identity;
• region;
• environment such as development, staging, or production;
• project/tagging convention;
• budget or size constraint when the change can incur cost.

For bp, prefer explicit per-invocation target flags:

bp sts GetCallerIdentity ---profile <profile> ---region <region>

Treat caller privilege as risk context, not as an authentication failure or an operation class. A console-login profile that resolves to the BytePlus root account is an accepted local-developer fast path. Warn once for that profile/account/region, then continue requested read-only work and apply the effect-based gates in security.md to each mutation. Do not require the developer to create an IAM user in the console before bounded development work, and do not request another approval solely because the caller is root. Offer least-privilege hardening as an optional workflow; require it only when the user's policy or target environment requires it.

Root caller status never replaces the normal effect-based gates: an already requested bounded private development change can proceed under the disclosed plan, while production, public exposure, IAM/networking, prepaid or unbounded cost, replacement, and destructive actions retain their exact-plan approval gates.

When authentication setup or caller privilege is itself at issue, present these paths without turning all three into prerequisites:

• Quick local (default): keep the current bp login profile, including a root profile, and use effect-based gates. This requires browser authorization but no IAM-console provisioning.
• Hardened local (optional): after explicit IAM-change approval, use the live IAM APIs to provision a scoped user, policy, project grant, or role. State that both IAM actions and STS AssumeRole are programmatic. Explain that restricted-user OAuth still needs one user-controlled browser sign-in and that raw access-key or AssumeRole responses cannot enter the agent transcript; do not promise seamless role switching without a tested credential-isolating helper.
• Managed team (optional): use Cloud Identity SSO when an organization already administers accounts, roles, and permission sets. One-time administration may be required, but SSO is not a prerequisite for solo local development.

When the developer specifically asks whether console work is required, lead with the answer: quick local use needs only the browser OAuth authorization, not IAM console provisioning. Then summarize the optional hardened-IAM and SSO paths in no more than a few sentences, including any remaining user-controlled browser step or credential-isolation limitation. Name IAM and STS as programmatic surfaces and retain the effect-based gate summary above. Do not bury this answer inside the deployment plan.

Before finishing an authentication or console-burden answer, check that it says:

1. quick local use does not require IAM-console provisioning;
2. root is valid but privileged and receives one warning, not a blanket block;
3. any IAM bootstrap is optional and requires explicit approval of the IAM changes;
4. IAM and STS are programmatic, but credentials must not enter the transcript;
5. restricted-user OAuth retains a user-controlled browser sign-in; and
6. Cloud Identity SSO is optional for teams and may require one-time administration.

Do not run an interactive login on the user's behalf without warning. For browser login, direct the user to bp login; for headless environments, use the documented remote flow. A non-default console-login profile is not automatically made current, so keep using explicit flags.

5. Select the control surface

Use the narrowest official interface that supports the task:

• Use nest or the Edge Functions MCP for Edge Functions and Pages workflows.
• Use BytePlus Cloud Control Terraform for supported, persistent multi-resource infrastructure when its authentication constraints are satisfied.
• Use bp for discovery, read operations, imperative control-plane actions, and gaps in Cloud Control.
• Use a current official product SDK or documented compatible tool for specialized data-plane operations such as TOS object transfer or ModelArk inference.
• Use an existing repository's working IaC or deployment tooling when it is safer and already authoritative.

Do not assume a universal BytePlus MCP or a universal Wrangler-like application CLI exists.

6. Discover live capability and schemas

Before composing a bp call, run:

bp --help
bp <service> --help
bp <service> <action> --help

For machine-readable discovery, use the bundled read-only wrapper:

python3 <skill-dir>/scripts/bp_catalog.py services
python3 <skill-dir>/scripts/bp_catalog.py actions <service>
python3 <skill-dir>/scripts/bp_catalog.py describe <service> <action>

The wrapper parses the installed CLI's help; it does not repair missing required-field, enum, permission, or regional metadata. Official action documentation remains required before a mutation.

Confirm the action's semantics in current official documentation. For Terraform, inspect the current Registry documentation and installed provider schema. For an SDK, inspect the installed package types and official versioned reference.

If no official programmable surface exposes the operation, report that limitation. Do not substitute a similarly named Volcano Engine API or an undocumented console endpoint.

7. Produce a change plan

Include:

• explicit account/profile, region, environment, and project;
• resources to reuse, create, update, replace, or delete;
• chosen interface and why it covers the operation;
• dependency order and expected outputs;
• cost, quota, public-access, IAM, networking, and data-loss effects;
• local file changes;
• verification checks;
• rollback or cleanup steps;
• unresolved assumptions.

Treat the user's request as authorization only for ordinary changes clearly necessary to the stated target. Request explicit confirmation before destructive replacement, deletion, production IAM/networking changes, public exposure, expensive compute/database/GPU capacity, or any material expansion of scope. Do not ask again when the user has already approved the exact disclosed plan.

8. Execute with a read-before-write discipline

For direct actions:

1. Read current state.
2. Confirm the target and live request schema.
3. Use an idempotency token where the API supports one.
4. Apply project/environment tags where supported.
5. Invoke the exact action with structured arguments.
6. Poll asynchronous operations with bounded retries.
7. Read state again and compare it with the plan.

For object or array bp parameters, always use --body with one JSON object or array and do not mix it with flattened API parameters. Dotted nested flags such as --ChargeInfo.ChargeType are not a reliable encoding contract. Do not put secrets in the body or shell history; use a credential-isolating SDK path when the CLI cannot accept protected input. Remember that the fixed CLI flags use three hyphens: ---profile, ---region, and ---endpoint.

For Terraform:

1. Pin a currently verified provider version.
2. Run formatting and validation.
3. Save a plan file.
4. Review replacements, deletions, sensitive values, and cost-bearing resources.
5. Apply the reviewed plan file, not a newly recalculated plan.
6. Verify application behavior after infrastructure convergence.

9. Deploy and verify the application

Verify at three levels:

• Control plane: resource status, configuration, region, network attachment, and identifiers.
• Data plane: health endpoint, expected request/response, storage or database access, and required model/API calls.
• Operations: logs, metrics, alarms, deployment history, and rollback availability.

Capture non-secret outputs needed by the application. If the repository needs an agent-readable resource map, copy byteplus.project.yaml and adapt it without storing credentials or treating it as authoritative cloud state.

10. Hand off clearly

Report:

• the target account/profile, region, and environment;
• files changed;
• resources created or changed and their non-secret IDs;
• commands or plans executed;
• verification evidence;
• remaining cost, security, quota, or manual steps;
• rollback and cleanup instructions.

Handle failures deliberately

• Stop on profile, account, region, permission, schema, quota, or pricing ambiguity before mutation.
• Preserve request IDs and sanitized error codes.
• Do not blindly retry create or delete operations; first determine whether the earlier call partially succeeded.
• Use bounded backoff for documented eventual consistency only.
• For partial deployment, inventory actual state and propose convergence or cleanup before continuing.
• Enable CLI debug logging only when needed, sanitize the result, and never expose credentials or full request bodies containing secrets.

Use the optional official Edge Functions MCP

Copy mcp.edge-functions.json only when the host supports MCP configuration and the task uses Edge Functions. Query MCP tools/list after startup and treat that live result as the capability contract; continue to use current CLI help for unsupported lifecycle commands. Do not present it as an account-wide BytePlus control-plane MCP.