Skip to main content
Version: Latest

Workspaces API Reference

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 not provided, the latest Ray version will be used.
  • --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.

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

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 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.

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.

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.

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.

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.

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.

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

Workspaces SDK​

anyscale.workspace.create​

Create a workspace.

Returns the id of the created workspace.

Arguments

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)

Workspaces Models​

WorkspaceConfig​

WorkspaceConfig(name: Optional[str] = None, image_uri: Optional[str] = None, containerfile: Optional[str] = None, compute_config: Union[anyscale.compute_config.models.ComputeConfig, Dict, str, NoneType] = None, idle_termination_minutes: Optional[int] = None, requirements: Union[str, List[str], NoneType] = None, env_vars: Optional[Dict[str, str]] = None, registry_login_secret: Optional[str] = None, ray_version: Optional[str] = None, project: Optional[str] = None, cloud: Optional[str] = None)

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.
  • compute_config (ComputeConfig | 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 not provided, the latest Ray version will be used.
  • 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

Workspaces CLI Legacy​

anyscale workspace create Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 create.

Usage

anyscale workspace create [OPTIONS]

Create a workspace on Anyscale.

Options

  • --name/-n: Name of the workspace to create.
  • --cloud-id: ID of the cloud to use for the workspace.
  • --cluster-env-build-id: ID of the cluster environment build to use for the workspace.
  • --docker: Custom docker image URI.
  • --python-version: Python version for the custom docker image.
  • --ray-version: Ray version for the custom docker image.
  • --compute-config-id: ID of the compute config to use for the workspace.

anyscale workspace run Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 run_command.

Usage

anyscale workspace run [OPTIONS] COMMAND

Run a command in a workspace, syncing files first if needed.

Options

  • --web-terminal/-w: Run the command in the webterminal. Progress can be tracked from the UI.
  • --as-job/-j: Run the command as a background job in a new cluster.
  • --no-push/-s: Whether to skip pushing files prior to running the command.

anyscale workspace ssh Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 ssh.

Usage

anyscale workspace ssh [OPTIONS] [ARGS]...

ssh into a workspace, you can also pass args to the ssh command. E.g. 'anyscale workspace ssh -- -L 8888:localhost:8888

Options

anyscale workspace start Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 start.

Usage

anyscale workspace start [OPTIONS]

Start an existing workspace on Anyscale.

Options

  • --name/-n: Name of existing workspace to start.

anyscale workspace terminate Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 terminate.

Usage

anyscale workspace terminate [OPTIONS]

Terminate a workspace on Anyscale.

Options

  • --name/-n: Name of existing workspace to terminate.

anyscale workspace pull Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 pull.

Usage

anyscale workspace pull [OPTIONS]

Pull files from a workspace on Anyscale.

Options

  • --pull-git-state: Also pull git state. This will add additional overhead.

anyscale workspace push Legacy​

warning

This command is deprecated. Upgrade to anyscale workspace_v2 push.

Usage

anyscale workspace push [OPTIONS]

Push files to a workspace on Anyscale.

Options

  • --push-git-state: Also push git state. This is currently unoptimized and will be very slow.

anyscale workspace clone Legacy​

Limited support

This command is not actively maintained. Use with caution.

Usage

anyscale workspace clone [OPTIONS]

Clone a workspace on Anyscale.

Options

  • --name/-n: Name of existing workspace to clone.

anyscale workspace cp Legacy​

Limited support

This command is not actively maintained. Use with caution.

Usage

anyscale workspace cp [OPTIONS] REMOTE_PATH LOCAL_PATH

Copy a file or a directory from workspace to local file system.

Examples

anyscale workspace cp /mnt/shared_objects/foo.py /tmp/copy_of_foo.py

anyscale workspace cp "~/default/README.md" ~/Downlaods

anyscale workspace cp "/tmp/" ~/Downlaods

Options