ms-studio-deploy

# ModelScope Studio Deployment > Verified live against ModelScope OpenAPI ｜ modelscope 1.37.1 / modelscope_hub 0.1.2 (2026-06-29) Deploy a local project to a ModelScope Studio. **This Skill uses OpenAPI as the source of truth**, with the `ms` CLI as an equivalent convenience alias, `modelscope_hub.HubApi` as the API-first Python client, and MCP tools as optional. ## Quick Decision Guide ``` User wants to... │ ├── Deploy a local project to a Studio │ └── Follow the 10 steps in "Full Deployment Workflow" below │ ├── Update an already-deployed Studio │ └── Modify code → git push → POST /studios/{o}/{r}/deploy (or ms deploy) │ ├── View Studio status/logs │ └── GET /studios/{o}/{r}/logs/run (or ms logs --log-type run) │ ├── Manage variables │ ├── Plaintext variables: GET/POST/PUT/DELETE /studios/{o}/{r}/variables │ └── Secrets: GET/POST/PUT/DELETE /studios/{o}/{r}/secrets (or ms secret ...) │ └── Repository file management / model & dataset operations └── hand off → ms-hub ``` ## Prerequisites ### 1. MODELSCOPE_API_KEY The entire workflow depends on this token (API authentication, Git push, variable/secret configuration); it must be confirmed first. ```bash # 1. First check the environment variable echo $MODELSCOPE_API_KEY # 2. If empty, try extracting from the git remote (may have been configured before) git remote -v 2>/dev/null | grep modelscope.cn ``` If the environment variable is empty but the git remote contains an address of the form `https://oauth2:<token>@www.modelscope.cn/studios/...` (or `www.modelscope.ai/...` for the international site), extract `<token>` from it as `MODELSCOPE_API_KEY`. If neither is available, guide the user: 1. Visit $MODELSCOPE_ENDPOINT/my/myaccesstoken to obtain a token 2. `export MODELSCOPE_API_KEY=your_token` > **Site routing:** this skill targets whichever site `$MODELSCOPE_ENDPOINT` points to (default domestic `https://modelscope.cn`; international `https://www.modelscope.ai`). Export `MODELSCOPE_ENDPOINT` plus a **site-scoped** token before deploying — the OpenAPI base and the git remote host below both derive from it. Full guidance: ms-hub → "Site selection & endpoint routing". ### 2. Runtime Environment ```bash pip install modelscope # Also provides the OpenAPI/SDK and the ms CLI ``` OpenAPI basic conventions: | Item | Value | |------|-----| | **Base URL** | `$MODELSCOPE_ENDPOINT/openapi/v1` (default `https://modelscope.cn`) | | **Authentication** | `Authorization: Bearer $MODELSCOPE_API_KEY` | | **Success response** | `{"success": true, "data": {...}, "request_id": "..."}` | | **Default branch** | `master` (not main) | ### 3. Git Environment Studio code is synced via Git; ensure Git is installed and user information is configured. ## Operations Overview: OpenAPI (source of truth) ↔ CLI ↔ Python | Operation | OpenAPI (source of truth) | ms CLI (equivalent alias) | `modelscope_hub.HubApi` (Python) | MCP tool (optional) | |------|---------------------|---------------------|-----------------------------------|------------------| | User info | `GET /users/me` | `ms whoami` | `api.whoami()` | `getCurrentUser` | | Create Studio | `POST /studios` | `ms create o/r --repo-type studio` | `api.create_repo("o/r", repo_type="studio", ...)` | `createStudio` | | Get details | `GET /studios/{o}/{r}` | `ms info o/r --repo-type studio` | `api.get_repo("o/r", repo_type="studio")` | `getStudio` | | Deploy/restart | `POST /studios/{o}/{r}/deploy` | `ms deploy o/r --repo-type studio` | `api.deploy_repo("o/r")` | `deployStudio` | | Stop | `POST /studios/{o}/{r}/stop` | `ms stop o/r --repo-type studio` | `api.stop_repo("o/r")` | `stopStudio` | | Logs | `GET /studios/{o}/{r}/logs/{run\|build}` | `ms logs o/r --log-type run` | `api.get_repo_logs("o/r", log_type="run")` | `getStudioLogs` | | Update settings | `PATCH /studios/{o}/{r}/settings` | `ms settings o/r --repo-type studio k=v` | `api.update_repo_settings("o/r","studio",**kw)` | `updateStudioSettings` | | Query available hardware | `GET /studios/hardware?sdk_type=gradio[&studio=o/r]` | none | none | `listHardware` | | Query SDK versions | `GET /studios/sdk-versions?sdk_type=gradio` | none | none | `listSdkVersions` | | Query base images | `GET /studios/base-images` | none | none | `listBaseImages` | | List plaintext variables | `GET /studios/{o}/{r}/variables` | none | none | `listStudioVariables` | | Add plaintext variable | `POST /studios/{o}/{r}/variables` | none | none | `addStudioVariable` | | Update plaintext variable | `PUT /studios/{o}/{r}/variables` | none | none | `updateStudioVariable` | | Delete plaintext variable | `DELETE /studios/{o}/{r}/variables` | none | none | `deleteStudioVariable` | | List secrets | `GET /studios/{o}/{r}/secrets` | `ms secret list o/r` | `api.list_secrets("o/r")` | `listStudioSecrets` | | Add secret | `POST /studios/{o}/{r}/secrets` | `ms secret add o/r K V` | `api.add_secret("o/r","K","V")` | `addStudioSecret` | | Update secret | `PUT /studios/{o}/{r}/secrets` | `ms secret update o/r K V` | `api.update_secret("o/r","K","V")` | `updateStudioSecret` | | Delete secret | `DELETE /studios/{o}/{r}/secrets` | `ms secret delete o/r K` | `api.delete_secret("o/r","K")` | `deleteStudioSecret` | > **`HubApi` is the same engine that drives the `ms` CLI** and is the API-first Python entry point: > ```python > from modelscope_hub import HubApi > api = HubApi(); api.login("$MODELSCOPE_API_KEY") > ``` > Note it is a different pair of classes from the legacy `modelscope.hub.api.HubApi`: the legacy version has not yet wired up Studio methods such as deploy/stop, whereas **the new `modelscope_hub.HubApi` has** (its `deploy_repo`/`stop_repo`/`get_repo_logs`/secret series default to `repo_type="studio"`). > **MCP tools (optional)** — the last column of the table above lists the equivalent tools provided by the `studio-mcp` service, with the same semantics as the OpenAPI call in the same row; when the agent has this service configured it can be called directly, and when it is not configured this column can be ignored. See the appendix at the end for first-time setup. ## Full Deployment Workflow > Each step leads with OpenAPI and provides an equivalent one-line CLI command. `${owner}`/`${repo}` are the Studio's owner and name. ### Step 1: Check the local Git repository ```bash [ -d .git ] && git remote -v 2>/dev/null | grep -E 'modelscope\.(cn|ai)/studios' ``` - Already has a Studio remote address → extract `owner` and `repo` from the URL, skip to Step 3 - None → continue to Step 2 ### Step 2: Analyze the project and get user info #### 2.1 Determine the SDK type | Type | Detection condition | Entry file | Notes | |------|----------|----------|------| | `gradio` | `app.py` imports gradio | `app.py` | Query `sdk_version`, `base_image`, `hardware` as needed | | `streamlit` | `app.py` uses streamlit | `app.py` | Query `base_image`, `hardware` as needed | | `docker` | `Dockerfile` present | `Dockerfile` | Port must be 7860 | | `static` | `index.html` present (pre-built) | `index.html` | Build step not supported; no hardware selection | Selection advice: `static` does not support a build step and the files must already be built; use `docker` for frontend projects that need building; use `docker` when unsure. > The `docker` type requires first completing Alibaba Cloud account binding and passing real-name verification on the ModelScope platform: https://modelscope.cn/docs/studios/docker , otherwise the image cannot be built. #### 2.2 Get user info ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/users/me" -H "Authorization: Bearer $MODELSCOPE_API_KEY" # Equivalent CLI: ms whoami ``` The `repo` is taken from the project directory name or specified by the user. ### Step 3: Create or update the Studio Before creating or changing settings, query the available options to avoid hardcoding outdated configuration: ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/hardware?sdk_type=${sdk_type}" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/sdk-versions?sdk_type=gradio" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/base-images" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" ``` For an existing Studio, you can append `&studio=${owner}/${repo}` to the hardware query so that free resources are returned according to that Studio's available quota. When selecting `hardware`, use the returned item's `name`; the paid resource format is `paid/<InstanceType>`. When selecting a Gradio `sdk_version`, use the returned item's `version`. When selecting `base_image`, use the returned item's `name`. **Paid-resource authorization requirement:** If you intend to set `hardware` to `paid/<InstanceType>` or the returned item has `resource_type=paid`, you must first explicitly tell the user that this will incur charges on the Alibaba Cloud account bound to their ModelScope account, and only create, update settings, or redeploy after obtaining the user's explicit authorization. Without authorization, only free resources may be selected. Check whether it already exists: ```bash curl "$MODELSCOPE_ENDPOINT/openapi/v1/studios/${owner}/${repo}" -H "Authorization: Bearer $MODELSCOPE_API_KEY" # Equivalent CLI: ms info ${owner}/${repo} --repo-type studio ``` **Does not exist → create** (before creating, proactively ask the user "public or private?", defaulting to private): ```bash curl -X POST "$MODELSCOPE_ENDPOINT/openapi/v1/studios" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "owner": "'"${owner}"'", "repo_name": "'"${repo}"'", "sdk_type": "gradio", "visibility": "private", "hardware": "platform/2v-cpu-16g-mem", "display_name": "My App" }' # Equivalent CLI: ms create ${owner}/${repo} --repo-type studio --sdk-type gradio --private ``` **Already exists → update settings as needed:** ```bash curl -X PATCH "$MODELSCOPE_ENDPOINT/openapi/v1/studios/${owner}/${repo}/settings" \ -H "Authorization: Bearer $MODELSCOPE_API_KEY" -H "Content-Type: application/json" \ -d '{"sdk_type": "gradio", "sdk_version": "6.2.0", "base_image": "ubuntu22.04-py311-torch2.9.1-modelscope1.35.0"}' # Equivalent CLI: ms settings ${owner}/${repo} --repo-type studio sdk_type=gradio sdk_version=6.2.0 ``` Changes to `sdk_type`, `sdk_version`, `base_image`, and `hardware` require redeployment to take effect. xGPU requires an application (https://modelscope.cn/docs/studios/xGPU). ### Step 4: Handle sensitive information Before pushing code, scan files for hardcoded sensitive information (API keys, tokens, passwords, etc.) and change them to read from environment variables instead: ```python # ❌ WRONG api_key = "sk-xxxxxxxxxxxx" # ✅ CORRECT import os api_key = os.environ.get("API_KEY") ``` Compile a list of variables for use in Step 6: put non-sensitive configuration in plaintext variables, and sensitive information such as API keys, tokens, and passwords in secrets. ### Step 5: Sync code to the Studio ⚠️ The only non-API step Code sync is done via **Git**; there is no corresponding OpenAPI/CLI endpoint. The default branch is `master`; force push is prohibited. ```bash # 1. Configure the remote repository (skip init if .git exists, skip add if the modelscope remote exists) [ -d .git ] || git init