--- title: "Workspaces SDK reference" description: "Customer-hosted cloud features" --- # Workspaces SDK reference #### Customer-hosted cloud features :::note Some features are only available on customer-hosted clouds. Reach out to [support@anyscale.com](mailto:support@anyscale.com) for info. ::: ## Workspaces SDK ### `anyscale.workspace.create` Create a workspace. Returns the id of the created workspace. **Arguments** - **`config` ([WorkspaceConfig](#workspaceconfig))**: The config for defining the workspace. **Returns**: str #### Examples ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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](#workspace) #### Examples ::::tabs :::tab[Python] ```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](#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](#workspacesortfield) | None) = None**: Field to sort by (STATUS, CREATED\_AT, LATEST\_STARTED\_AT). Defaults to status then created\_at. - **`sort_order` (str | [WorkspaceSortOrder](#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](#workspace)\] #### Examples ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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 ::::tabs :::tab[Python] ```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](#updateworkspaceconfig))**: The config for updating the workspace. Unspecified fields will retain their current values, while specified fields will be updated. **Returns**: None #### Examples ::::tabs :::tab[Python] ```python import anyscale anyscale.workspace.update( 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](/reference/sdk/compute-config.md#computeconfig) | [MultiResourceComputeConfig](/reference/sdk/compute-config.md#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 ```python 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 ::::tabs :::tab[YAML] ```yaml name: my-workspace idle_termination_minutes: 220 env_vars: key: value requirements: /tmp/requirements.txt tags: team: mlops env: prod ``` ::: :::tab[Python] ```python 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](#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](#workspaceconfig) | Dict | None)**: Full workspace configuration. Only populated for get() operations, not list(). #### Python Methods ```python def to_dict(self) -> Dict[str, Any] """Return a dictionary representation of the model.""" ``` #### Examples ::::tabs :::tab[Python] ```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](/reference/sdk/compute-config.md#computeconfig) | [MultiResourceComputeConfig](/reference/sdk/compute-config.md#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 ```python 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 ::::tabs :::tab[YAML] ```yaml name: new-workspace-name idle_termination_minutes: 220 env_vars: key: value requirements: /tmp/requirements.txt tags: team: mlops env: prod ``` ::: :::tab[Python] ```python from anyscale.workspace.models import UpdateWorkspaceConfig config = UpdateWorkspaceConfig( name="new-workspace-name", idle_termination_minutes=220, env_vars={"key": "value"}, requirements="/tmp/requirements.txt", ) ``` ::: :::: --- Previous: [User](/reference/sdk/user.md) | Next: [Anyscale base images](/reference/base-images.md)