pai dsw instance — interactive modeling - Platform For AI

Manage the full lifecycle of Data Science Workshop (DSW) interactive modeling instances.

instance create

pai dsw instance create --name NAME [flags]

Parameter	Type	Default	Description
`--name`	string	—	Instance name. Required.
`--image`	string	—	Image ID (mutually exclusive with --image-url).
`--image-url`	string	—	Image repository URL (mutually exclusive with --image).
`--image-auth`	string	—	Base64-encoded authentication for private images.
`--ecs-spec`	string	—	Pay-as-you-go: ECS instance type, such as ecs.gn7i-c8g1.2xlarge.
`--resource-id`	string	—	Subscription: resource quota ID.
`--cpu`	string	—	Subscription: number of CPU cores.
`--memory`	string	—	Subscription: memory size, such as 8GB.
`--gpu`	int	—	Subscription: number of GPUs.
`--gpu-type`	string	—	Subscription: GPU model, such as V100, A100, or T4.
`--shared-memory`	string	—	Subscription: shared memory size, such as 8GB.
`--priority`	int	—	Subscription: scheduling priority from 1 (lowest) to 9 (highest).
`--oversold-type`	string	—	Overselling policy: `ForceQuotaOverSold`, `AcceptQuotaOverSold`, or `ForbiddenQuotaOverSold`.
`--workspace-id`	string	config	Workspace ID.
`--dataset`	stringArray	—	Dataset mount in the format id:mount_path[:version]. Can be specified multiple times.
`--datasets`	string	—	Dataset JSON array (API field format).
`--cloud-disk-size`	string	—	Cloud disk capacity, such as 100Gi. Mutually exclusive with --cloud-disks.
`--cloud-disks`	string	—	Cloud disk configuration JSON array.
`--env`	stringArray	—	Environment variables in KEY=VALUE format. Can be specified multiple times.
`--label`	stringArray	—	Instance labels in KEY=VALUE format. Can be specified multiple times.
`--tag`	stringArray	—	Instance tags in KEY=VALUE format. Can be specified multiple times.
`--startup-script`	string	—	Script to run on each startup.
`--user-command`	string	—	UserCommand JSON (mutually exclusive with --startup-script).
`--idle-timeout`	int	—	Idle timeout in minutes before automatic shutdown.
`--driver`	string	—	NVIDIA driver version, such as 535.230.02.
`--accessibility`	string	—	Instance visibility: `PRIVATE` `PUBLIC`.
`--ssh-public-key`	string	—	SSH public key. Enables SSH access when set.
`--ssh-access-type`	string	—	SSH access types, comma-separated: intranet, internet.
`--ssh-port`	string	22	SSH listening port.
`--ssh-external-port`	string	Auto	SSH port mapped to the public network.
`--ssh-eip-id`	string	—	Elastic IP Address (EIP) ID for SSH (used with NAT gateway).
`--ssh-nat-gateway-id`	string	—	NAT gateway ID.
`--ssh-nlb-gateway-id`	string	—	NLB gateway ID (mutually exclusive with NAT/EIP).
`--user-vpc`	string	—	VPC network configuration JSON.
`--spot-spec`	string	—	Pay-as-you-go: spot instance configuration JSON.
`--service`	stringArray	—	Custom service/port forwarding configuration. Can be specified multiple times.
`--affinity`	string	—	Scheduling affinity configuration JSON.
`--assign-node-spec`	string	—	Node scheduling configuration JSON.
`--credential-config`	string	—	Instance credential configuration JSON.
`--docker-config`	string	—	Docker configuration JSON.
`--dynamic-mount`	string	—	Dynamic mount configuration JSON.
`--migration-options`	string	—	Instance migration options (Lingjun + persistent storage scenario).
`--workspace-source`	string	—	Working directory storage source.
`--dry-run`	bool	false	Print the assembled request body in PascalCase (matching the API format) without creating an instance. Use with --body-json to reuse the template.
`--body-json`	string	—	Complete request body JSON (overrides all above options).
`--generate-skeleton`	bool	false	Output a JSON request template and exit. Use to generate a --body-json template.
`--override / --override-string / --override-unset`	stringArray	—	Modify request body fields before submission. See --override request body editing.

Examples

# 1. Pay-as-you-go: minimal creation (ECS spec + image)
pai dsw instance create \
  --name my-instance \
  --ecs-spec ecs.gn7i-c8g1.2xlarge \
  --image pytorch:2.0.1-gpu-py310-cu118-ubuntu20.04

# 2. Subscription: use resource quota (use cpu/gpu/memory, not ecs-spec)
pai dsw instance create \
  --name my-prepaid \
  --resource-id quota-a1b2c3d4e5f6 \
  --cpu 8 --memory 16GB --gpu 1 --gpu-type A100 \
  --image pytorch:2.0.1-gpu-py310-cu118-ubuntu20.04

# 3. Mount dataset + idle auto-shutdown (shuts down after 60 minutes of inactivity)
pai dsw instance create \
  --name my-instance \
  --ecs-spec ecs.gn7i-c8g1.2xlarge \
  --image pytorch:2.0.1-gpu-py310-cu118-ubuntu20.04 \
  --dataset d-abc123:/mnt/data \
  --idle-timeout 60

# 4. Enable SSH remote access
pai dsw instance create \
  --name my-instance \
  --ecs-spec ecs.gn7i-c8g1.2xlarge \
  --image pytorch:2.0.1-gpu-py310-cu118-ubuntu20.04 \
  --ssh-public-key "ssh-rsa AAAA..." \
  --ssh-access-type internet

# 5. --generate-skeleton to generate a request template (for --body-json advanced configuration)
pai dsw instance create --generate-skeleton > instance.json
# Edit instance.json and then submit
pai dsw instance create --body-json "$(cat instance.json)"

instance list

pai dsw instance list [flags]

Parameter	Type	Default	Description
`--workspace-id`	string	config	Workspace ID.
`--status`	string	—	Filter by status `Running` `Stopped` `Failed`.
`--order`	string	—	Sort order: `ASC` `DESC`.
`--page`	int	1	Page number.
`--page-size`	int	20	Items per page.
`--columns`	string	—	Custom output columns, comma-separated. Default: instance_id, instance_name, status, payment_type, ecs_spec, image_id, workspace_id, gmt_create_time, gmt_modified_time.

instance get

pai dsw instance get <instance-id> [--all] [--raw] [--show-secrets]

Parameter	Type	Default	Description
`--all`	bool	false	Show all fields in table view (json/yaml output always includes all fields).
`--show-secrets`	bool	false	Display service passwords and image repository credentials in plaintext. By default, only `(set)`/`(not set)` is shown.
`--raw`	bool	false	Output the raw API response: credentials as-is, with HTTP envelope, and unset API fields omitted instead of null.

instance update

pai dsw instance update <instance-id> [flags]

Update instance properties. Uses patch semantics: only specified fields are sent. Unspecified fields retain their current values. To remove a configuration, use the corresponding --remove-* flag (requires confirmation).

Parameter	Type	Default	Description
`--name, --image, --image-url, --ecs-spec, --priority, --driver, --startup-script, --accessibility`	—	No change	Replace the corresponding field (same meaning as create).
`--dataset / --datasets / --env`	stringArray	No change	Replace the entire configuration group (not incremental).
`--remove-datasets, --remove-env, --remove-vpc, --remove-driver, --remove-spot, --remove-credential, --remove-user-command, --remove-forward-infos, --remove-assign-node, --remove-migration-options`	bool	false	Remove the corresponding configuration. Requires confirmation (or add `-y`).
`--body-json`	string	—	Complete UpdateInstance request body (PascalCase). Supports `@file` / `@-`. Flags passed alongside override its fields.
`--override / --override-string / --override-unset`	stringArray	—	Modify request body fields before submission. See --override request body editing.
`--dry-run`	bool	false	Print the request body without sending.
`-y, --yes`	bool	false	Skip confirmation prompts for --remove-*.

instance apply / save / render — declarative management

Manage instances through configuration files (kubectl-style workflow): save exports a running instance configuration → edit → render validates offline → apply creates or updates.

pai dsw instance save <instance-id> [--out FILE] [--format yaml|json] [--force]
pai dsw instance render -f <file>
pai dsw instance apply -f <file> [--dry-run] [--prune] [-y]

Parameter	Type	Default	Description
`--out` (save)	string	stdout	Write to file. Refuses to overwrite existing files unless `--force` is set.
`--format` (save)	string	yaml	Export format: `yaml` `json`.
`-f, --file` (render/apply)	string	—	Instance configuration file (JSON/YAML). Use `-` for stdin. Required.
`--instance-id` (apply)	string	Lookup by name	Specify the target instance directly, skipping lookup. Overrides InstanceId in the file.
`--dry-run` (apply)	bool	false	Compare with the running instance and show what would be created or changed. Outputs `unchanged` if no differences.
`--prune` (apply)	bool	false	Remove configurations not declared in the file (datasets, environment variables, VPC, driver, etc.). Requires confirmation.
`--override family` (render/apply)	stringArray	—	Modify configuration fields before applying. See --override request body editing.

# 1. Export the running instance configuration (only fields accepted by the create request; credentials are never written)
pai dsw instance save dsw-xxxx --out instance.yaml

# 2. Validate offline after editing (no API calls or credentials needed; can run in CI)
pai dsw instance render -f instance.yaml

# 3. Preview changes and then apply
pai dsw instance apply -f instance.yaml --dry-run
pai dsw instance apply -f instance.yaml

# Pipeline: export and validate in one step
pai dsw instance save dsw-xxxx | pai dsw instance render -f -

Note

apply locates the target instance by name in the configuration: creates it if it doesn't exist, updates it if it does, and sends no request if there are no changes (idempotent). Suitable for managing instance configurations in Git.

instance delete

pai dsw instance delete <instance-id> [-y] [--dry-run]

Parameter	Type	Default	Description
`-y, --yes`	bool	false	Skip confirmation prompts (required for scripting and automation).
`--dry-run`	bool	false	Preview the operation without executing.

Note

If the deleted instance is the current context set by instance use, the CLI automatically clears that context to prevent subsequent commands from targeting a nonexistent instance.

instance start / stop

pai dsw instance start <instance-id> [--dry-run]
pai dsw instance stop <instance-id> [--dry-run]

Parameter	Type	Default	Description
`--dry-run`	bool	false	Preview the operation without executing.

instance wait

pai dsw instance wait <instance-id> --for <status>

Parameter	Type	Default	Description
`--for`	string	—	Target status. Required: `Running` `Stopped` `Failed` `Deleted`.
`--interval`	int	5	Polling interval in seconds.
`--timeout`	int	300	Maximum wait time in seconds.

instance exec

pai dsw instance exec [instance-id] [-- command...]

Parameter	Type	Default	Description
`--code`	string	—	Execute a Python code snippet.
`--file`	string	—	Upload a local file to the instance and execute it.
`--remote-path`	string	/tmp/dsw_exec_<name>	Remote upload destination (trailing / indicates a directory).
`--cwd`	string	—	Remote working directory.
`--timeout`	int	120	Command execution timeout in seconds.
`--via`	string	gateway	Data plane channel: `gateway` `vpc` `internet`.

Note

Wrap commands that contain pipes or redirections in quotes: pai dsw instance exec -- "ls -la | grep model"

Examples

# 1. Run a shell command (with pipe, must be quoted)
pai dsw instance exec -- "ls -la /workspace | grep .pt"

# 2. Execute a Python code snippet
pai dsw instance exec --code "import torch; print(torch.cuda.is_available())"

# 3. Upload and run a local script on the instance
pai dsw instance exec --file ./train.py

# 4. Specify remote working directory and timeout
pai dsw instance exec --cwd /workspace --timeout 600 -- "python eval.py"

# 5. Upload a script to a specific path and run it
pai dsw instance exec --file ./test.py --remote-path /workspace/test.py

# 6. Execute through VPC channel (when the instance has no public network access)
pai dsw instance exec --via vpc -- "nvidia-smi"

instance cp

pai dsw instance cp <src> <dst> [flags]

Upload: pai dsw instance cp ./local.txt dsw:/workspace/file.txt

Download: pai dsw instance cp dsw:/workspace/out.csv ./

Parameter	Type	Default	Description
`--instance`	string	Current context	Target instance ID (required when no context is set).
`--via`	string	gateway	Data plane channel: `gateway` `vpc` `internet`.
`--dry-run`	bool	false	Preview the operation without executing.

Examples

# 1. Upload a local file to the instance
pai dsw instance cp ./train.py dsw:/workspace/train.py

# 2. Download a file from the instance to local
pai dsw instance cp dsw:/workspace/model.pt ./

# 3. Upload an entire directory
pai dsw instance cp ./data/ dsw:/workspace/data/

# 4. Specify the instance when no context is set
pai dsw instance cp ./config.yaml dsw:/workspace/ --instance i-xxxxxxxx

# 5. Transfer through VPC channel
pai dsw instance cp ./large-file.bin dsw:/workspace/ --via vpc

# 6. Preview the operation (no actual transfer)
pai dsw instance cp ./train.py dsw:/workspace/train.py --dry-run

instance logs

pai dsw instance logs [instance-id] [flags]

Parameter	Type	Default	Description
`--follow`	bool	false	Continuously follow the event stream (similar to tail -f).
`--since`	string	—	Show only events after the specified time (e.g., 30m, 2h, 3d).
`--max-events`	int	2000	Maximum number of events to return.

instance metrics

pai dsw instance metrics <instance-id> --metric <NAME> [flags]

Read CloudMonitor metrics for an instance, such as CPU/GPU utilization, memory, and disk. Use --list-metrics to view the available metric catalog.

Warning

Metrics return data only for subscription instances. Pay-as-you-go instances return an empty sequence (the API succeeds but with no data). The CLI checks the billing type and shows a clear message — otherwise an empty table looks like the instance is idle.

Parameter	Type	Default	Description
`--metric`	string	—	CloudMonitor metric name. Required (or use --list-metrics to browse the catalog).
`--list-metrics`	bool	false	Print the metric catalog and exit.
`--start / --end`	string	-1h / now	Time window: RFC3339 or relative offset (e.g., -90m, -6h, -2d).
`--period`	string	60	Sampling interval in seconds. Supported values: `60` `300`.
`--length`	int	1440	Maximum data points per page (API limit: 1440).
`--next-token`	string	—	Pagination token (from the next_token field in `-o json` output; table view only indicates whether more pages exist).
`--dimensions`	string	Auto-built	Override CloudMonitor dimension JSON. For example, add a "gpu" dimension to limit CARD_* metrics to a single GPU. Not needed for typical use.
`--namespace`	string	acs_pai_dsw	CloudMonitor namespace. Usually doesn't need to be changed.

# List available metrics
pai dsw instance metrics dsw-xxxx --list-metrics

# GPU memory utilization for the last hour
pai dsw instance metrics dsw-xxxx --metric INSTANCE_GPU_ACCELERATOR_MEMORY_UTIL

# Specify time window and sampling interval (5-minute granularity)
pai dsw instance metrics dsw-xxxx --metric INSTANCE_CPU_UTIL \
  --start 2026-08-16T00:00:00Z --end 2026-08-16T06:00:00Z --period 300

Note

CARD_* metrics produce one time series per GPU (distinguished by the gpu column). A 16-GPU instance generates 16 rows per time point. The API paginates by GPU: when a long time window hits the limit, it keeps all timestamps but drops entire GPUs, making results look complete when they're not. The CLI reports this as truncated — shorten the window or increase --period to see all data.

instance sanity-check

pai dsw instance sanity-check <instance-id> [--type ssh] [flags]

Run a health check on an instance and wait for the result. The check is an asynchronous task: by default, the CLI creates the task and polls until it reaches a terminal state. Use --async to get only the task ID and return immediately, then use --task-id to read the result later.

Parameter	Type	Default	Description
`--type`	string	ssh	Check type. Known value: `ssh`. Other values are passed through to the API.
`--async`	bool	false	Return the task ID immediately without waiting for the result.
`--task-id`	string	—	Read the result of an existing task (mutually exclusive with --async).
`--verbose`	bool	false	Return per-checkpoint details (without this flag, only issues are returned).
`--interval / --timeout`	int	5 / 300	Polling interval and maximum wait time in seconds.

instance use / current

pai dsw instance use <instance-id> [--via gateway|vpc|internet] [--force]
pai dsw instance current

Parameter	Type	Default	Description
`--via`	string	gateway	Set the default data plane channel.
`--force`	bool	false	Set the context even if the VPC or Internet channel is unreachable.

After setting the context, subsequent exec, cp, and rootfs-usage commands can omit the instance ID.

instance list-ecs-specs

pai dsw instance list-ecs-specs --accelerator-type <CPU|GPU>

Parameter	Type	Default	Description
`--accelerator-type`	string	—	Accelerator type. Required: `CPU` `GPU`.
`--sort-by`	string	—	Sort field.
`--order`	string	—	Sort order: `ASC` `DESC`.
`--page`	int	1	Page number.
`--page-size`	int	100	Items per page.
`--columns`	string	—	Custom output columns. Default: instance_type, accelerator_type, cpu, memory, gpu, gpu_type, gpu_memory_size, is_available.

instance rootfs-usage

pai dsw instance rootfs-usage [instance-id] [flags]

Analyze the disk usage of the instance root filesystem. Automatically excludes mounted datasets, cloud disks, and non-system paths such as /mnt/workspace.

Parameter	Type	Default	Description
`--path`	string	/	Root path for analysis.
`-d, --depth`	int	2	Directory display depth.
`--exclude`	stringArray	—	Additional paths to exclude. Can be specified multiple times.
`--show-excludes`	bool	true	Show the excluded paths in the output.
`--interval`	int	5	Scan polling interval in seconds.
`--timeout`	int	300	Maximum wait time in seconds.
`--via`	string	gateway	Data plane channel: `gateway` `vpc` `internet`.

instance mcp-config

pai dsw instance mcp-config [instance-id] [--via internet|vpc]

Output standard mcpServers JSON configuration that can be pasted directly into MCP-compatible clients such as Cursor or Claude Code.

Parameter	Type	Default	Description
`--via`	string	internet	Address type to use: `internet` `vpc`.

instance proxy

pai dsw instance proxy start [instance-id] [--port 9806] [-d]
pai dsw instance proxy stop [instance-id] [--all]
pai dsw instance proxy list

Start a local HTTP proxy that forwards MCP traffic to a DSW instance. MCP clients connect to http://localhost:<port>/mcp. No Alibaba Cloud credentials are required.

Parameter	Type	Default	Description
`--port` (start)	int	9806	Local listening port.
`-d, --background` (start)	bool	false	Run the proxy process in the background.
`--all` (stop)	bool	false	Stop all running proxies.