Workspaces SDK reference

View Markdown

Workspaces SDK reference

Customer-hosted cloud features

note

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

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

Python

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

Python

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

Python

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

Python

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

Python

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

Python

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_file, 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

Python

import anyscale

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

`anyscale.workspace.pull`

Pull a workspace to a local directory.

New files will be created, existing files will be overwritten. With delete=True, files in the local directory that don't exist in the workspace will be removed. Excluded files (like .git) are preserved and not deleted even with delete=True.

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).
local_dir (str | None) = None: The local directory to pull the workspace to. If not provided, the current working directory will be used.
pull_git_state (bool) = False: Whether to pull the git state of the workspace.
rsync_args (List[str] | None) = None: Additional arguments to pass to rsync.
delete (bool) = False: Whether to delete files in the local directory that are not in the workspace. Excluded files (e.g., .git or custom exclusions) are preserved and not deleted.
direct_ssh (bool) = False: Whether to use direct SSH connection (port 22) instead of SSH-over-HTTPS tunnel.

Returns: None

Examples

Python

import anyscale

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

`anyscale.workspace.push`

Push a local directory to a workspace.

New files will be created, existing files will be overwritten. With delete=True, files in the workspace that don't exist locally will be removed. Excluded files (like .git) are preserved and not deleted even with delete=True.

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).
local_dir (str | None) = None: The local directory to push to the workspace. If not provided, the current working directory will be used.
push_git_state (bool) = False: Whether to push the git state of the workspace.
rsync_args (List[str] | None) = None: Additional arguments to pass to rsync.
delete (bool) = False: Whether to delete files in the workspace that are not in the local directory. Excluded files (e.g., .git or custom exclusions) are preserved and not deleted.
direct_ssh (bool) = False: Whether to use direct SSH connection (port 22) instead of SSH-over-HTTPS tunnel.

Returns: None

Examples

Python

import anyscale

anyscale.workspace.push(
    name="my-workspace",
    local_dir="~/workspace",
)

`anyscale.workspace.get`

Get a workspace.

Args: include_config: If True (default), fetch full workspace config. Set to False for efficiency.

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).
include_config (bool) = True: Whether to include full workspace config details such as compute and build config. Defaults to True.

Returns: Workspace

Examples

Python

import anyscale
from anyscale.workspace.models import Workspace

workspace: Workspace = anyscale.workspace.get(
    name='my-workspace',
)

`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

Python

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

Python

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

Python

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

Python

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

Python

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

YAML
Python

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

from anyscale.workspace.models import WorkspaceConfig

config = WorkspaceConfig(
    name="my-workspace",
    idle_termination_minutes=220,
    env_vars={"key": "value"},
    requirements="/tmp/requirements.txt",
)

`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

Python

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

YAML
Python

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

from anyscale.workspace.models import UpdateWorkspaceConfig

config = UpdateWorkspaceConfig(
    name="new-workspace-name",
    idle_termination_minutes=220,
    env_vars={"key": "value"},
    requirements="/tmp/requirements.txt",
)

Customer-hosted cloud features​

Workspaces SDK​

anyscale.workspace.create​

Examples​

anyscale.workspace.start​

Examples​

anyscale.workspace.terminate​

Examples​

anyscale.workspace.status​

Examples​

anyscale.workspace.wait​

Examples​

anyscale.workspace.generate_ssh_config_file​

Examples​

anyscale.workspace.run_command​

Examples​

anyscale.workspace.pull​

Examples​

anyscale.workspace.push​

Examples​

anyscale.workspace.get​

Examples​

anyscale.workspace.list​

Examples​

anyscale.workspace.add_tags​

Examples​

anyscale.workspace.remove_tags​

Examples​

anyscale.workspace.list_tags​

Examples​

anyscale.workspace.update​

Examples​

Workspaces models​

WorkspaceConfig​

Fields​

Python Methods​

Examples​

WorkspaceState​

Values​

Workspace​

Fields​

Python Methods​

Examples​

WorkspaceSortField​

Values​

WorkspaceSortOrder​

Values​

UpdateWorkspaceConfig​

Fields​

Python Methods​

Examples​

Customer-hosted cloud features

Workspaces SDK

`anyscale.workspace.create`

Examples

`anyscale.workspace.start`

Examples

`anyscale.workspace.terminate`

Examples

`anyscale.workspace.status`

Examples

`anyscale.workspace.wait`

Examples

`anyscale.workspace.generate_ssh_config_file`

Examples

`anyscale.workspace.run_command`

Examples

`anyscale.workspace.pull`

Examples

`anyscale.workspace.push`

Examples

`anyscale.workspace.get`

Examples

`anyscale.workspace.list`

Examples

`anyscale.workspace.add_tags`

Examples

`anyscale.workspace.remove_tags`

Examples

`anyscale.workspace.list_tags`

Examples

`anyscale.workspace.update`

Examples

Workspaces models

`WorkspaceConfig`

Fields

Python Methods

Examples

`WorkspaceState`

Values

`Workspace`

Fields

Python Methods

Examples

`WorkspaceSortField`

Values

`WorkspaceSortOrder`

Values

`UpdateWorkspaceConfig`

Fields

Python Methods

Examples