Skip to main content

Workspaces API Reference (0.26.90)

View Markdown

Workspaces API Reference (0.26.90)

note

This is archived documentation for version 0.26.90. For the current documentation, see current documentation.

Customer-hosted cloud features​

note

Some features are only available on customer-hosted clouds. Reach out to support@anyscale.com for info.

Workspaces CLI​

anyscale workspace_v2 create​

Usage

anyscale workspace_v2 create [OPTIONS]

Create a workspace on Anyscale.

Options

  • -f/--config-file: Path to a YAML config file to deploy. When deploying from a file, import path and arguments cannot be provided. Command-line flags will overwrite values read from the file.
  • -n/--name: Name of the workspace to create.
  • --image-uri: Container image to use for the workspace. This is exclusive with --containerfile.
  • --registry-login-secret: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.
  • --containerfile: Path to a containerfile to build the image to use for the workspace. This is exclusive with --image-uri.
  • --ray-version: The Ray version (X.Y.Z) to the image specified by --image-uri. This is only used when --image-uri is provided. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.
  • --compute-config: Named compute configuration to use for the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • --project: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
  • -r/--requirements: Path to a requirements.txt file containing dependencies for the workspace. These will be installed on top of the image.
  • --env: Environment variables to set for the workspace. The format is 'key=value'. This argument can be specified multiple times. When the same key is also specified in the config file, the value from the command-line flag will overwrite the value from the config file.
  • --tag: Tag in key=value (or key:value) format. Repeat to add multiple.

Examples​

$ anyscale workspace_v2 create -f config.yml
(anyscale +2.7s) Workspace created successfully id: expwrk_jstjkv15a1vmle2j1t59s4bm35
(anyscale +3.9s) Applied dynamic requirements to workspace id: my-workspace
(anyscale +4.8s) Applied environment variables to workspace id: my-workspace

$ cat config.yml
name: my-workspace
idle_termination_minutes: 10
env_vars:
    HUMPDAY: WEDS
requirements: requirements.txt

anyscale workspace_v2 start​

Usage

anyscale workspace_v2 start [OPTIONS]

Start a workspace.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.

Examples​

$ anyscale workspace_v2 start --name my-workspace
(anyscale +5.8s) Starting workspace 'my-workspace'

anyscale workspace_v2 terminate​

Usage

anyscale workspace_v2 terminate [OPTIONS]

Terminate a workspace.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.

Examples​

$ anyscale workspace_v2 terminate --name my-workspace
(anyscale +2.5s) Terminating workspace 'my-workspace'

anyscale workspace_v2 status​

Usage

anyscale workspace_v2 status [OPTIONS]

Get the status of a workspace.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.

Examples​

$ anyscale workspace_v2 status --name my-workspace
(anyscale +2.3s) STARTING

anyscale workspace_v2 wait​

Usage

anyscale workspace_v2 wait [OPTIONS]

Wait for a workspace to reach a terminal state.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.
  • --timeout-s: The maximum time in seconds to wait for the workspace to reach the desired state. Default to 30 minutes.
  • --state: The desired terminal state to wait for. Default is 'RUNNING'.

Examples​

$ anyscale workspace_v2 wait --name my-workspace --state RUNNING
(anyscale +2.5s) Waiting for workspace 'expwrk_jstjkv15a1vmle2j1t59s4bm35' to reach target state RUNNING, currently in state: RUNNING
(anyscale +2.8s) Workspace 'expwrk_jstjkv15a1vmle2j1t59s4bm35' reached target state, exiting

anyscale workspace_v2 ssh​

Usage

anyscale workspace_v2 ssh [OPTIONS]

SSH into a workspace.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

You may pass extra args for the ssh command, for example to setup port forwarding: anyscale workspace_v2 ssh -n workspace-name -- -L 9000:localhost:9000

Use the --legacy flag to bypass HTTPS SSH and use the legacy connection method directly.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.
  • --legacy: Use legacy SSH connection method, bypassing HTTPS SSH.

Examples​

$ anyscale workspace_v2 ssh --name my-workspace
Authorized uses only. All activity may be monitored and reported.
Warning: Permanently added '[0.0.0.0]:5020' (ED25519) to the list of known hosts.
(base) ray@ip-10-0-24-60:~/default$

anyscale workspace_v2 run_command​

Usage

anyscale workspace_v2 run_command [OPTIONS] COMMAND

Run a command in a workspace.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.

Examples​

$ anyscale workspace_v2 run_command --name my-workspace "echo hello world"
Authorized uses only. All activity may be monitored and reported.
Warning: Permanently added '[0.0.0.0]:5020' (ED25519) to the list of known hosts.
hello world

anyscale workspace_v2 pull​

Usage

anyscale workspace_v2 pull [OPTIONS]

Pull the working directory of a workspace. New files will be created, existing files will be overwritten.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

This command depends on rsync, please make sure it is installed on your system.

The --delete flag removes files in the local directory that don't exist in the workspace. Excluded files (like .git unless --pull-git-state is used) are preserved and not deleted.

You may pass extra args for the rsync command, for example to exclude files: anyscale workspace_v2 pull -n workspace-name -- --exclude='log.txt'

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.
  • --local-dir: Local directory to pull the workspace directory to. If not provided, the current directory will be used.
  • --pull-git-state: Pull the git state of the workspace.
  • --delete: Delete files in the local directory that are not in the workspace. Excluded files are preserved.
  • --direct-ssh: Use direct SSH connection (port 22) instead of SSH-over-HTTPS tunnel.

Examples​

$ anyscale workspace_v2 pull --name my-workspace --local-dir my-local
Warning: Permanently added '54.212.209.253' (ED25519) to the list of known hosts.
Authorized uses only. All activity may be monitored and reported.
Warning: Permanently added '[0.0.0.0]:5020' (ED25519) to the list of known hosts.
receiving incremental file list
created directory my-local
./
my-local/
my-local/main.py

sent 118 bytes  received 141 bytes  172.67 bytes/sec
total size is 0  speedup is 0.00

anyscale workspace_v2 push​

Usage

anyscale workspace_v2 push [OPTIONS]

Push a local directory to a workspace. New files will be created, existing files will be overwritten.

To specify the workspace by name, use the --name flag. To specify the workspace by id, use the --id flag. Either name or id should be used, specifying both will result in an error.

This command depends on rsync, please make sure it is installed on your system.

The --delete flag removes files in the workspace that don't exist locally. Excluded files (like .git unless --push-git-state is used) are preserved and not deleted.

You may pass extra args for the rsync command, for example to exclude files: anyscale workspace_v2 push -n workspace-name -- --exclude='log.txt'

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.
  • --local-dir: Local directory to push to the workspace. If not provided, the current directory will be used.
  • --push-git-state: Push the git state of the workspace.
  • --delete: Delete files in the workspace that are not in the local directory. Excluded files are preserved.
  • --direct-ssh: Use direct SSH connection (port 22) instead of SSH-over-HTTPS tunnel.

Examples​

$ anyscale workspace_v2 push --name my-workspace --local-dir my-local
Warning: Permanently added '52.10.22.124' (ED25519) to the list of known hosts.
Authorized uses only. All activity may be monitored and reported.
Warning: Permanently added '[0.0.0.0]:5020' (ED25519) to the list of known hosts.
sending incremental file list
my-local/
my-local/main.py

sent 188 bytes  received 39 bytes  151.33 bytes/sec
total size is 0  speedup is 0.00

anyscale workspace_v2 update​

Usage

anyscale workspace_v2 update [OPTIONS] WORKSPACE_ID

Update an existing workspace on Anyscale.

Options

  • -f/--config-file: Path to a YAML config file to update. Command-line flags will overwrite values read from the file. Unspecified fields will retain their current values, while specified fields will be updated.
  • -n/--name: New name of the workspace.
  • --image-uri: New container image to use for the workspace. This is exclusive with --containerfile.
  • --registry-login-secret: Name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.
  • --containerfile: Path to a containerfile to build the image to use for the workspace. This is exclusive with --image-uri.
  • --ray-version: New Ray version (X.Y.Z) to use with the image specified by --image-uri. This is only used when --image-uri is provided. If not provided, the latest Ray version will be used.
  • --compute-config: New named compute configuration to use for the workspace.
  • -r/--requirements: Path to a requirements.txt file containing dependencies for the workspace. These will be installed on top of the image.
  • --env: New environment variables to set for the workspace. The format is 'key=value'. This argument can be specified multiple times. When the same key is also specified in the config file, the value from the command-line flag will overwrite the value from the config file.

Examples​

$ anyscale workspace_v2 update expwrk_6l2ldwbu8299ympgltn725ciak --config-file config.yaml
(anyscale +2.3s) Workspace updated successfully id: expwrk_6l2ldwbu8299ympgltn725ciak
(anyscale +5.6s) Applied dynamic requirements to workspace id: expwrk_6l2ldwbu8299ympgltn725ciak
(anyscale +9.1s) Applied environment variables to workspace id: expwrk_6l2ldwbu8299ympgltn725ciak

$ cat config.yaml
name: my-workspace
idle_termination_minutes: 10
env_vars:
    HUMPDAY: WEDS
requirements: requirements.txt

anyscale workspace_v2 get​

Usage

anyscale workspace_v2 get [OPTIONS]

Retrieve workspace details by name or ID.

Use --name to specify by name or --id for the workspace ID; using both will result in an error.

Options

  • --id/--workspace-id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.
  • --project: Named project to use for the workpsace. If not provided, the default project for the cloud will be used.
  • -j/--json: Output the workspace in a structured JSON format.
  • --yaml: Output as YAML.
  • -v/--verbose: Include verbose details.

Examples​

$ anyscale workspace_v2 get --name my-workspace
id: my-workspace-id
name: my-workspace
state: RUNNING

anyscale workspace_v2 list​

Usage

anyscale workspace_v2 list [OPTIONS]

List workspaces.

Options

  • --workspace-id/--id: ID of the workspace to display.
  • --name/-n: Substring to match against the workspace name.
  • --project: Filter workspaces by project name.
  • --cloud: Filter workspaces by cloud name.
  • --created-by-me: List workspaces created by me only.
  • --state/-s: Filter by workspace state (repeatable). Allowed: STARTING, UPDATING, RUNNING, TERMINATING, TERMINATED, ERRORED, UNKNOWN
  • --include-archived: Include archived workspaces in the results.
  • --tag: Filter by tags. Can be repeated for multiple tags. Tags with the same key are ORed, different keys are ANDed. Example: --tag team:mlops --tag team:infra --tag env:prod filters to (team: mlops OR infra) AND env:prod.
  • --max-items: Max total items (only with --no-interactive).
  • --page-size: Items per page (max 50).
  • --interactive/--no-interactive: Use interactive paging.
  • --sort: Sort by FIELD (prefix with '-' for desc). Allowed: STATUS, CREATED_AT, LATEST_STARTED_AT
  • -j/--json: Emit structured JSON to stdout.
  • -v/--verbose: Show all fields including IDs and metadata.

Examples​

$ anyscale workspace_v2 list
Listing workspaces with:
• name              = <any>
• project           = <any>
• cloud             = <any>
• created_by_me     = False
• states            = <all>
• tags              = <none>
• include_archived  = False
• sort              = <none>
• mode              = interactive
• per-page limit    = 10
• max-items total   = all

View your Workspaces in the UI at https://console.anyscale.com/workspaces

NAME              STATE     PROJECT           CLOUD        CREATED BY              CREATED AT
my-workspace-1    RUNNING   proj_abc          cld_xyz      user@example.com        2024-01-15 10:30
my-workspace-2    STARTING  proj_abc          cld_xyz      user@example.com        2024-01-16 14:20
Fetched 2 workspaces.

anyscale workspace_v2 tags add​

Usage

anyscale workspace_v2 tags add [OPTIONS]

Add or update tags on a workspace.

Options

  • --id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: Cloud name (used when resolving by name).
  • --project: Project name (used when resolving by name).
  • --tag: Tag in key=value (or key:value) format. Repeat to add multiple.

Examples​

$ anyscale workspace_v2 tags add --name my-workspace --tag team=ml --tag env=prod

anyscale workspace_v2 tags remove​

Usage

anyscale workspace_v2 tags remove [OPTIONS]

Remove tags by key from a workspace.

Options

  • --id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: Cloud name (used when resolving by name).
  • --project: Project name (used when resolving by name).
  • --key: Tag key to remove. Repeatable.

Examples​

$ anyscale workspace_v2 tags remove --name my-workspace --key team --key env

anyscale workspace_v2 tags list​

Usage

anyscale workspace_v2 tags list [OPTIONS]

List tags for a workspace.

Options

  • --id: Unique ID of the workspace.
  • --name/-n: Name of the workspace.
  • --cloud: Cloud name (used when resolving by name).
  • --project: Project name (used when resolving by name).
  • --json: JSON output.

Examples​

$ anyscale workspace_v2 tags list --name my-workspace
Output
Tags:
KEY   VALUE
env   prod
team  ml

Workspaces SDK​

anyscale.workspace.create​

Create a workspace.

Returns the id of the created workspace.

Arguments

  • config (WorkspaceConfig): The config for defining the workspace.

Returns: str

Examples​

import anyscale
from anyscale.workspace.models import WorkspaceConfig

anyscale.workspace.create(
    WorkspaceConfig(
        name="my-workspace",
        idle_termination_minutes=120,
    ),
)

anyscale.workspace.start​

Start a workspace.

Returns the id of the started workspace.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).

Returns: str

Examples​

import anyscale

anyscale.workspace.start(
    name="my-workspace",
)

anyscale.workspace.terminate​

Terminate a workspace.

Returns the id of the terminated workspace.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).

Returns: str

Examples​

import anyscale

anyscale.workspace.terminate(
    name="my-workspace",
)

anyscale.workspace.status​

Get the status of a workspace.

Returns the status of the workspace.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).

Returns: str

Examples​

import anyscale

status = anyscale.workspace.status(
    name="my-workspace",
)

anyscale.workspace.wait​

Wait for a workspace to reach a terminal state.

Returns the status of the workspace.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
  • timeout_s (float) = 1800.0: The maximum time to wait for the workspace to reach a terminal state.
  • state (str) = RUNNING: The desired terminal state to wait for, defaults to RUNNING.

Returns: str

Examples​

import anyscale

anyscale.workspace.wait(
    name="my-workspace",
)

anyscale.workspace.generate_ssh_config_file​

Generate an SSH config file for a workspace.

Returns the hostname and path to the generated config file.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
  • ssh_config_path (str | None) = None: The directory to write the generated config file to.

Returns: Tuple[str, str]

Examples​

import anyscale
import subprocess

host_name, config_file = anyscale.workspace.generate_ssh_config_file(
    name="my-workspace",
)

# run an ssh command using the generated config file
subprocess.run(["ssh", "-F", config_path, host_name, "ray --version"])

anyscale.workspace.run_command​

Run a command in a workspace.

Returns a subprocess.CompletedProcess object.

Arguments

  • name (str | None) = None: Name of the workspace.
  • id (str | None) = None: Unique ID of the workspace
  • cloud (str | None) = None: The Anyscale Cloud to run this workload on. If not provided, the organization default will be used (or, if running in a workspace, the cloud of the workspace).
  • project (str | None) = None: Named project to use for the workspace. If not provided, the default project for the cloud will be used (or, if running in a workspace, the project of the workspace).
  • command (str): The command to run.
  • kwargs (Dict[str, Any]): Additional arguments to pass to subprocess.run.

Examples​

import anyscale

process = anyscale.workspace.run_command(
    name="my-workspace",
    command="ray_version",
    capture_output=True,
    text=True,
)
print(process.stdout)

anyscale.workspace.list​

List workspaces with optional filters.

Returns an iterator of Workspace objects. By default, filters to non-terminated states and does not fetch the workspace config data.

Arguments

  • workspace_id (str | None) = None: Fetch a single workspace by ID.
  • name (str | None) = None: Filter by workspace name (substring match).
  • project (str | None) = None: Named project to filter by.
  • cloud (str | None) = None: Named cloud to filter by.
  • creator_id (str | None) = None: Filter workspaces by creator user ID.
  • state_filter (List[WorkspaceState] | List[str] | None) = None: List of states to include. May be WorkspaceState enums or case-insensitive strings.
  • tags_filter (Dict[str, List[str]] | None) = None: Filter by tags. Dict mapping tag keys to lists of values. Tags with the same key are ORed, different keys are ANDed.
  • include_config (bool) = False: If True, fetch full config for each workspace (expensive). Defaults to False for efficiency.
  • sort_field (str | WorkspaceSortField | None) = None: Field to sort by (STATUS, CREATED_AT, LATEST_STARTED_AT). Defaults to status then created_at.
  • sort_order (str | WorkspaceSortOrder | None) = None: Sort order (ASC or DESC). Defaults to appropriate order for the sort field.
  • max_items (int | None) = None: Maximum number of items to return. If None, all items are returned.
  • page_size (int | None) = None: Number of items to fetch per API call (affects performance, not total results).

Returns: ResultIterator[Workspace]

Examples​

import anyscale
from anyscale.workspace.models import Workspace

for workspace in anyscale.workspace.list(max_items=10):
    print(f"{workspace.name}: {workspace.state}")

anyscale.workspace.add_tags​

Upsert (add/update) tag key/value pairs for a workspace.

Arguments

  • id (str | None) = None: ID of the workspace. Provide either id or name.
  • name (str | None) = None: Name of the workspace. Provide either id or name.
  • cloud (str | None) = None: Cloud name (used when resolving by name).
  • project (str | None) = None: Project name (used when resolving by name).
  • tags (Dict[str, str]): Key/value tags to upsert as a map {key: value}.

Examples​

import anyscale

anyscale.workspace.add_tags(id="ws_123", tags={"team": "mlops", "env": "prod"})

anyscale.workspace.remove_tags​

Remove tags by key from a workspace.

Arguments

  • id (str | None) = None: ID of the workspace. Provide either id or name.
  • name (str | None) = None: Name of the workspace. Provide either id or name.
  • cloud (str | None) = None: Cloud name (used when resolving by name).
  • project (str | None) = None: Project name (used when resolving by name).
  • keys (List[str]): List of tag keys to remove.

Examples​

import anyscale

anyscale.workspace.remove_tags(id="ws_123", keys=["team", "env"])

anyscale.workspace.list_tags​

List tags for a workspace as a key/value mapping.

Arguments

  • id (str | None) = None: ID of the workspace. Provide either id or name.
  • name (str | None) = None: Name of the workspace. Provide either id or name.
  • cloud (str | None) = None: Cloud name (used when resolving by name).
  • project (str | None) = None: Project name (used when resolving by name).

Returns: Dict[str, str]

Examples​

import anyscale

tags: dict[str, str] = anyscale.workspace.list_tags(name="my-workspace")

anyscale.workspace.update​

Update a workspace.

Arguments

  • id (str | None) = None: Unique ID of the workspace
  • config (UpdateWorkspaceConfig): The config for updating the workspace. Unspecified fields will retain their current values, while specified fields will be updated.

Returns: None

Examples​

import anyscale

anyscale.workspace.update(
    id="<workspace-id>",
    config=UpdateWorkspaceConfig(
        name="new-workspace-name",
        idle_termination_minutes=120,
    ),
)

Workspaces Models​

WorkspaceConfig​

Configuration options for a workspace.

Fields​

  • name (str | None): The name of the workspace
  • image_uri (str | None): URI of an existing image. Exclusive with containerfile.
  • containerfile (str | None): The file path to a containerfile that will be built into an image before running the workload. Exclusive with image_uri.
  • tags (Dict[str, str] | None): Tags to associate with the workspace.
  • compute_config (ComputeConfig | MultiResourceComputeConfig | Dict | str | None): The name of an existing registered compute config (including version) or an inlined ComputeConfig object.
  • idle_termination_minutes (int | None): the time in minutes after which the workspace is terminated when idle.
  • requirements (str | List[str] | None): A list of pip requirements or a path to a requirements.txt file for the workload.
  • env_vars (Dict[str, str] | None): A dictionary of environment variables that will be set for the workload.
  • registry_login_secret (str | None): A name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.
  • ray_version (str | None): The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.
  • project (str | None): The project for the workload. If not provided, the default project for the cloud will be used.
  • cloud (str | None): The Anyscale Cloud to run this workload on. If not provided, the organization default will be used.

Python Methods​

def __init__(self, **fields) -> WorkspaceConfig
    """Construct a model with the provided field values set."""

def options(self, **fields) -> WorkspaceConfig
    """Return a copy of the model with the provided field values overwritten."""

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

name: my-workspace
idle_termination_minutes: 220
env_vars:
    key: value
requirements: /tmp/requirements.txt
tags:
  team: mlops
  env: prod

WorkspaceState​

Possible states for a workspace.

Values​

  • STARTING: The workspace is starting up.
  • UPDATING: The workspace is updating.
  • RUNNING: The workspace is running.
  • TERMINATING: The workspace is terminating.
  • TERMINATED: The workspace is terminated.
  • ERRORED: The workspace is in an error state.
  • UNKNOWN: The workspace state

Workspace​

Workspace information including metadata and state.

Fields​

  • id (str): Unique identifier of the workspace.
  • name (str): The name of the workspace.
  • state (WorkspaceState): The current state of the workspace.
  • project_id (str | None): Project identifier that owns this workspace.
  • cloud_id (str | None): Cloud identifier where the workspace is running.
  • creator_id (str | None): Identifier of the user who created the workspace.
  • creator_email (str | None): Email address of the user who created the workspace.
  • created_at (datetime | None): Timestamp when the workspace was created.
  • last_started_at (datetime | None): Timestamp when the workspace was last started.
  • cluster_id (str | None): Cluster identifier for the workspace.
  • config (WorkspaceConfig | Dict | None): Full workspace configuration. Only populated for get() operations, not list().

Python Methods​

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

import anyscale
from anyscale.workspace.models import Workspace

workspace: Workspace = anyscale.workspace.get(name="workspace-name")
first_workspace: Workspace = next(anyscale.workspace.list(max_items=1), None)

WorkspaceSortField​

Fields available for sorting workspaces.

Values​

  • STATUS: Sort by workspace status (active first by default).
  • CREATED_AT: Sort by creation timestamp.
  • LATEST_STARTED_AT: Sort by most recent start time.

WorkspaceSortOrder​

Enum for sort order directions.

Values​

  • ASC: Sort in ascending order.
  • DESC: Sort in descending order.

UpdateWorkspaceConfig​

Configuration options for updating a workspace.

Fields​

  • name (str | None): The name of the workspace
  • image_uri (str | None): URI of an existing image. Exclusive with containerfile.
  • containerfile (str | None): The file path to a containerfile that will be built into an image before running the workload. Exclusive with image_uri.
  • tags (Dict[str, str] | None): Tags to associate with the workspace.
  • compute_config (ComputeConfig | MultiResourceComputeConfig | Dict | str | None): The name of an existing registered compute config (including version) or an inlined ComputeConfig object.
  • idle_termination_minutes (int | None): the time in minutes after which the workspace is terminated when idle.
  • requirements (str | List[str] | None): A list of pip requirements or a path to a requirements.txt file for the workload.
  • env_vars (Dict[str, str] | None): A dictionary of environment variables that will be set for the workload.
  • registry_login_secret (str | None): A name or identifier of the secret containing credentials to authenticate to the docker registry hosting the image. This can only be used when 'image_uri' is specified and the image is not hosted on Anyscale.
  • ray_version (str | None): The Ray version (X.Y.Z) specified for this image specified by either an image URI or a containerfile. If you don't specify a Ray version, Anyscale defaults to the latest Ray version available at the time of the Anyscale CLI/SDK release.

Python Methods​

def __init__(self, **fields) -> UpdateWorkspaceConfig
    """Construct a model with the provided field values set."""

def options(self, **fields) -> UpdateWorkspaceConfig
    """Return a copy of the model with the provided field values overwritten."""

def to_dict(self) -> Dict[str, Any]
    """Return a dictionary representation of the model."""

Examples​

name: new-workspace-name
idle_termination_minutes: 220
env_vars:
    key: value
requirements: /tmp/requirements.txt
tags:
    team: mlops
    env: prod