aliyun appmanager is an Agent-friendly CLI tool for one-click deployment of applications (App) and AI Agents to Alibaba Cloud ECS. It supports non-interactive mode (--non-interactive), structured JSON output (--output json), and streaming NDJSON responses.
Default behavior: When user invokes /alibabacloud-ecs-code-deploy without specifying a project path or URL, deploy the current working directory project to Alibaba Cloud ECS. If user provides a git URL, clone it to the current directory first, then cd into the cloned directory and proceed with deployment.
> EXECUTION ORDER: The Agent MUST follow the "Complete Deployment Workflow" section at the bottom of this document for the correct execution sequence. The Task sections below are organized by topic for reference — their numbering does NOT imply execution order.
Before executing any step, the Agent MUST create a todo list with ALL of the following items. Do NOT omit any item. Do NOT start deployment until the todo list is created.
Todo list (Deploy to Alibaba Cloud ECS):
[ ] 0. Resolve $SKILL_DIR (cross-platform path — MUST run first; see "Step 0" below)
[ ] 1. Environment pre-check (MUST run deploy_toolkit.py check; manual commands FORBIDDEN as replacement)
[ ] 2. Obtain project (clone git URL here if needed; skip for local projects)
── Check whether .appmanager/config.yaml already exists (repeat-deploy shortcut) ──
│ Exists + new ECS (no instanceId) → skip 3-5, start from 5.5 (price check)
│ Exists + existing ECS (has instanceId) → skip 3-5.5, jump to 6 (deploy)
│ Does not exist → proceed normally from 3
───────────────────────────────────────────────────────────────────────────────
[ ] 3. Read project (README.md -> quick-deploy method) + identify type (agent / app)
[ ] 4. Ask user for deployment config (region + new ECS / existing ECS)
[ ] 5. Init + generate scripts (appmanager init -> write start/stop scripts to config.yaml)
[ ] 5.5. Pre-deploy price check + risk warning (MUST run deploy_toolkit.py price; confirm price / OSS billing / existing-ECS impact / group overwrite item by item)
[ ] 6. Deploy (MUST run deploy_toolkit.py deploy; manual deploy command FORBIDDEN as replacement)
[ ] 7. Verify (MUST run deploy_toolkit.py verify; manual status command FORBIDDEN as replacement)
[ ] 8. Output final result (console link + cost reminder + management commands)
> ⛔ SCRIPT-FIRST RULE: Steps 1, 5, 6, 7 have a dedicated toolkit script at $SKILL_DIR/scripts/deploy_toolkit.py (where $SKILL_DIR is resolved in Step 0 below — works on Qoder, Claude Code, and any other platform). The Agent MUST run the corresponding subcommand DIRECTLY as the FIRST and ONLY action for that step — NEVER run manual CLI commands (like aliyun version, version checks, credential checks) BEFORE or INSTEAD of the script. The script already handles ALL checks internally. Manual commands are ONLY allowed as fallback if the script file itself does not exist.
>
> ❌ WRONG (Step 1): Run aliyun version → check version → run ~/.aliyun/appmanager-venv/bin/python ... → check version → THEN run deploy_toolkit.py check
> ✅ CORRECT (Step 1): Run python3 "$SKILL_DIR/scripts/deploy_toolkit.py" check → if exit 1, fix the issue it reports → if script file missing, THEN fall back to manual checks
> Item 6 is NON-NEGOTIABLE. An Agent that skips log verification and directly outputs "deployment succeeded" has NOT completed this skill correctly. If deploy_toolkit.py verify exits 1 (failed), the Agent MUST fix the issue and re-deploy before proceeding to item 7.
$SKILL_DIR — Cross-Platform Path> The toolkit script lives at $SKILL_DIR appears below. Hardcoding any platform-specific path is FORBIDDEN.
See references/skill-dir-resolution.md for the full 10-candidate detection algorithm, the export + test -f verify snippet, and Pattern A / Pattern B / ⛔ Anti-pattern usage rules.
Quick recap (read the reference for details):
export SKILL_DIR="/abs/path" then later python3 "$SKILL_DIR/scripts/deploy_toolkit.py" python3 "/abs/path/scripts/deploy_toolkit.py" SKILL_DIR=/path python3 "$SKILL_DIR/..." — outer shell expands $SKILL_DIR BEFORE the prefix assignment, producing /scripts/deploy_toolkit.py and ENOENT. If you see python3: can't open file '/scripts/deploy_toolkit.py', switch to Pattern A or B.Primary action: Run python3 "$SKILL_DIR/scripts/deploy_toolkit.py" check — it checks CLI version + appmanager-cli version + credentials in one run. Only if the script file is missing, use the fallback in references/init-and-credentials.md.
> MUST — Handling unmet environment prerequisites: When check exits 1 because the aliyun CLI is missing or older than 3.3.19 (or appmanager-cli is missing/outdated), the Agent MUST NOT stop the workflow silently. The required flow is:
> 1. CLI NOT installed → Auto-install directly without asking user — execute the install command (see snippet below or references/init-and-credentials.md for the right arch), then re-run deploy_toolkit.py check to confirm.
> 2. CLI already installed → ASK the user first — show the detected version + the required version + the upgrade command, and ask for explicit consent (e.g. "aliyun CLI 3.3.4 is already installed but below the required >= 3.3.19 for appmanager; approve upgrade (overwrite-install into /usr/local/bin, requires sudo)?"). Never assume yes; never paste credentials.
> - On approval — execute the install/upgrade command, then re-run deploy_toolkit.py check to confirm.
> - On refusal — stop with the refusal as the reason. Do NOT continue with the older version (deployment will fail anyway).
>
> The toolkit's check output already includes an → AGENT: DO NOT stop. ASK user ... line for each fixable issue — follow it verbatim (except for the "not installed" case, which is auto-handled).
>
> MUST — Upgrade method priority (avoid the "repeated upgrade" pitfall: /usr/local/bin/ is often shadowed by earlier PATH entries like /opt/homebrew/bin):
> 1. brew-managed (check prints "managed by Homebrew") -> brew upgrade aliyun-cli; do NOT overwrite /usr/local/bin/ again.
> 2. sudo available -> overwrite into /usr/local/bin/, then verify: hash -r && which -a aliyun && aliyun version.
> 3. No sudo -> install to ~/bin/, ask user to approve appending export PATH="$HOME/bin:$PATH" to ~/.zshrc / ~/.bashrc.
>
> After install/upgrade, ALWAYS rerun deploy_toolkit.py check to confirm. If which -a aliyun still shows the old binary first, fix PATH order — DO NOT repeat the same overwrite.
> ⛔ MUST configure AI-Mode: Agent MUST ensure AI-Mode is properly configured before running any aliyun appmanager commands. deploy_toolkit.py check handles this internally; the commands below are for manual fallback only.
aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-ecs-code-deploy"
aliyun plugin update
aliyun configure ai-mode show # verify: enabled=true, user-agent set
aliyun configure ai-mode disable # only when troubleshooting
deploy_toolkit.py check already validates credentials. Only if credentials are missing/invalid, see references/init-and-credentials.md for the default-credential-chain remediation flow.
> ⛔ PREFER OAuth OVER AK: This skill SHOULD guide users to use OAuth authentication as the PRIMARY method for providing Alibaba Cloud permissions. OAuth is more secure and convenient than AccessKey (no long-term secret storage needed). The Agent MUST present OAuth as the first option before mentioning AK-based methods.
>
> OAuth Login Guide: Instruct the user to run the following command in their terminal:
> ```bash
> aliyun configure --mode OAuth --profile oauth
> ```
> This is an interactive command that will:
> 1. Open a browser with an authorization link — user clicks to authorize
> 2. Prompt for region (e.g. cn-hangzhou, cn-beijing) — user enters their preferred region
> 3. Prompt for language (e.g. zh) — user enters their preferred language
>
> After OAuth setup completes, verify with: aliyun sts get-caller-identity --profile oauth
>
> ⛔ SA-2.12 — DO NOT explicitly handle AK/SK: This skill MUST rely on the aliyun CLI/SDK default credential chain (OAuth / ECS RAM Role / env vars / pre-existing ~/.aliyun/config.json). The Agent NEVER asks the user to paste AccessKey/Secret/STS-Token values into the chat, NEVER puts raw AK/SK in tool-call arguments or scripts, and NEVER echoes credential values. When credentials are missing, instruct the user to configure them out-of-band (their own terminal/shell profile/RAM role) and only re-verify via aliyun sts get-caller-identity. Full remediation flow → references/init-and-credentials.md.
>
> CRITICAL PROHIBITION: NEVER run standalone appmanager or aliyun appmanager login.
> CRITICAL ORDERING RULE: Before scanning any project files, the Agent MUST read README.md (or README) in the project root. This is ALWAYS the first action in Task 3.
What to extract from README:
pip install -r requirements.txt && python main.py, npm install && npm start)Step A: List what README provides to the user.
Step B: Select method by priority:
| Priority | Method Type | Action |
|---|---|---|
| ---------- | ------------ | -------- |
| 1 (HIGHEST) | Native CLI / package manager install (npm install -g, pip install, go install) | Use directly |
| 2 | Native build + run (pip install && python main.py, npm install && npm start) | Use, install runtime |
| 3 | Script-based deploy (bash deploy.sh) | Must confirm non-interactive |
| 4 (LOWEST) | Docker / docker-compose | Only when no higher priority exists; check China accessibility |
Step C: Execute based on scenario:
> Why README first? Most projects document the exact build/run commands. Auto-detecting from files alone is error-prone.
| Condition | Type |
|---|---|
| ----------- | ------ |
Project depends on agentscope | agent |
| Everything else (langchain, mcp, autogen, web services, tools, etc.) | app |
--nameUse the project directory name (lowercased, hyphens). Inform user: Default app name uses the directory name .
--region and ECS target (MUST ask user)Agent MUST ask both questions together in ONE message:
> 1. Which region do you want to deploy to?
> - Shanghai (cn-shanghai) / Hangzhou (cn-hangzhou) / Beijing (cn-beijing) / Shenzhen (cn-shenzhen) / Guangzhou (cn-guangzhou) / Chengdu (cn-chengdu) / Nanjing (cn-nanjing) / Hong Kong (cn-hongkong)
>
> 2. New ECS or existing ECS?
> - New ECS (auto-create instance, pay-as-you-go)
> - Existing ECS (please provide the instance ID, e.g. i-bp1xxxxxxxx)
NEVER use zone-based labels like "East China 1" / "North China 2". NEVER add descriptions. City names only.
> ⚠️ REGION PROPAGATION CHECK (MANDATORY): The chosen region MUST be passed verbatim to appmanager init --region, written into config.yaml common.deployment.regionId, AND attached as --region to every subsequent deploy_toolkit.py {price,deploy,verify} invocation. Mismatch / omission triggers InvalidParameter: DeployRegionId is invalid from the OOS API.
--port (App type only, OPTIONAL)Only specify when the project actually listens on HTTP. Skip for background services (bots, workers, CLI tools). If needed but unknown, default to 8080. Agent type does NOT use --port.
See references/init-and-credentials.md for all init flag combinations.
Creates .appmanager/config.yaml. Does NOT support --overwrite — delete .appmanager/ first if exists.
For ALL project types, the Agent MUST generate deployment scripts and write them into .appmanager/config.yaml.
common.scripts.start and common.scripts.stop (NEVER top-level scripts)| Indicator Files | Language |
|---|---|
| ----------------- | ---------- |
package.json / .js / .ts | Node.js |
requirements.txt / pyproject.toml / *.py | Python |
pom.xml / build.gradle / *.java | Java |
go.mod / *.go | Go |
composer.json / *.php | PHP |
docker-compose.yml / Dockerfile | Docker |
| Language | Must Read | Why |
|---|---|---|
| ---------- | ----------- | ----- |
| Python | pyproject.toml, requirements.txt | Entry point, deps |
| Node.js | package.json | scripts.start, main field |
| Java | pom.xml or build.gradle | JAR name |
| Go | go.mod | Module → binary name |
| PHP | composer.json | Framework detection |
| Docker | docker-compose.yml / Dockerfile | Services, ports |
[project.scripts] in pyproject.toml → main.py → app.py → manage.pyscripts.start → main field → index.js → server.jsfind ... -name "*.jar" | head -1 → java -jarfind ... -type f -perm /111composer install --no-dev → php artisan serve or php -Sdocker compose up -d / docker compose down| Rule | Requirement | ||
|---|---|---|---|
| ------ | ------------- | ||
| ⛔ MANDATORY zip extract | Start script MUST: find zip → mkdir -p → unzip -o → cd. Without this, project dir DOES NOT EXIST on ECS | ||
| Runtime install | MUST install language runtime FIRST (ECS is bare) | ||
| Install unzip | `command -v unzip &>/dev/null \ | \ | $PKG_MGR install -y unzip` |
| Idempotent | Safe to run multiple times | ||
| ⛔ Log file FIXED path | MUST be /root/app.log and /root/app.pid. verify script hardcodes these paths | ||
| Log append | Always >> (never >) | ||
| PID file | echo $! > /root/app.pid after nohup ... & | ||
| Background run | nohup ... >> /root/app.log 2>&1 & | ||
| Stop old process | `[ -f /root/app.pid ] && kill "$(cat /root/app.pid)" 2>/dev/null \ | \ | true` |
| App dir | /root/{app_name} | ||
| No heredoc | NEVER use << 'EOF' inside scripts — breaks YAML. Use printf or python3 -c | ||
| MANDATORY tail log | End with sleep 3 && cat /root/app.log for verification capture | ||
| ⛔ Stop script: NO exit | MUST NOT contain exit. Deploy system concatenates stop+start — exit kills the entire process |
> ECS instances are bare Linux (typically Alibaba Cloud Linux, RHEL-based, uses yum/dnf).
For script templates, language install commands, and config.yaml writing method, see references/script-templates.md.
> MANDATORY: Before deploying, run deploy_toolkit.py price. The script outputs the price estimate (with OSS extra-billing reminder) and, when applicable, a risk warning block. The Agent MUST present every flagged item to the user and obtain explicit confirmation BEFORE running deploy.
python3 "$SKILL_DIR/scripts/deploy_toolkit.py" price --config .appmanager/config.yaml
=== AGENT_CONFIRM_REQUIRED ===: present the complete price + risk warning to the user, confirm item by item.The Agent MUST confirm up to 3 items (price + OSS fees / existing-ECS risk / group overwrite choice) — see references/deploy-output-and-management.md § "Pre-deploy Price Check: Confirmation Items" for detailed descriptions and example phrasing.
> Until ALL applicable confirmations are complete, the Agent MUST NOT invoke deploy_toolkit.py deploy.
aliyun appmanager <agent|app> deploy --overwrite --output json
> STOP after deploy success — status: success only means orchestration completed. Agent MUST run Task 6 verification before outputting results.
> ⛔ MANDATORY FAILURE GATE: After ANY deploy failure (exit 1, timeout, or ReleaseCancelled), the Agent MUST run deploy_toolkit.py verify IMMEDIATELY — BEFORE any fix attempt, fallback to manual commands, or partial output. Skipping verify after a failure is FORBIDDEN and counts as skill failure.
> Semantics of ReleaseCancelled: it means the start script on ECS failed or timed out. It does NOT mean "someone cancelled the deploy". The only correct next action: run deploy_toolkit.py verify -> read the log -> fix the script -> redeploy.
> Known failure patterns: Before ad-hoc troubleshooting, check references/lessons-learned.md for previously identified deployment failure patterns and proven fixes.
Failure-handling flow:
deploy_toolkit.py verify to fetch /root/app.log (DO NOT skip).> status: Deployed does NOT mean the application is running. The Agent MUST run verify and semantically analyze the log.
deploy_toolkit.py verify (auto-reads parameters from config.yaml).See references/deploy-output-and-management.md for:
Before outputting results, Agent MUST print the exact Deployment self-check report template (see Workflow Step 7.5). Skipping the report = skill failure (not an optional summary). If any item is ❌, fix it BEFORE outputting Step 8.
> 📘 Hands-on walk-through with concrete inputs/outputs and edge cases (Python Flask example): see references/tutorial-flask-app.md.
> ⛔ MANDATORY EXECUTION RULE: The Agent MUST follow this sequence exactly. For steps that specify a script (steps 1, 5, 6), the Agent MUST run the script — NEVER manually replicate the script's logic with individual commands. The Task sections above are REFERENCE ONLY (for understanding what the scripts do internally or as fallback if scripts are missing).
python3 "/abs/path/scripts/deploy_toolkit.py" ...SKILL_DIR=/path python3 "$SKILL_DIR/..." — outer shell expands $SKILL_DIR/scripts/deploy_toolkit.py and ENOENT.python3 "$SKILL_DIR/scripts/deploy_toolkit.py" check
aliyun version, ~/.aliyun/appmanager-venv/bin/python -c "...",rm -rf ~/.aliyun/appmanager-venv (auto-recreates on next aliyunaliyun appmanager runaliyun configure interactive) — NEVERagentscope; everything else is "app"rm -rf .appmanager deletes the existing deployment config.pwd shows expected path).appmanager (NEVER absolute, NEVER with variables)python3 "$SKILL_DIR/scripts/deploy_toolkit.py" price --config .appmanager/config.yaml
appmanager price (order-billed resources: ECS/EIP/bandwidth) + the trailing 📦 OSS extra-billing reminderpython3 "$SKILL_DIR/scripts/deploy_toolkit.py" deploy \
--type
aliyun appmanager deploy directly without this scriptpython3 "$SKILL_DIR/scripts/deploy_toolkit.py" verify \
--type
aliyun appmanager status + manual log analysis instead of this script#
#
共 3 个版本