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

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.

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.

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.

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.
-v/--verbose: Include verbose details.

Examples

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

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

Python

import anyscale

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

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

YAML
Python

name: my-workspace
idle_termination_minutes: 220
env_vars:
    key: value
requirements: /tmp/requirements.txt

from anyscale.workspace.models import WorkspaceConfig

config = WorkspaceConfig(
    name="my-workpsace",
    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.
--project-id: ID of the project to associate with the workspace.
--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.
--verbose/-v: Verbose mode

`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

Customer-hosted cloud features​

Workspaces CLI​

anyscale workspace_v2 create​

Examples​

anyscale workspace_v2 start​

Examples​

anyscale workspace_v2 terminate​

Examples​

anyscale workspace_v2 status​

Examples​

anyscale workspace_v2 wait​

Examples​

anyscale workspace_v2 ssh​

Examples​

anyscale workspace_v2 run_command​

Examples​

anyscale workspace_v2 pull​

Examples​

anyscale workspace_v2 push​

Examples​

anyscale workspace_v2 update​

Examples​

anyscale workspace_v2 get​

Examples​

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​

Workspaces Models​

WorkspaceConfig​

Fields​

Python Methods​

Examples​

Workspaces CLI Legacy​

anyscale workspace create Legacy​

anyscale workspace run Legacy​

anyscale workspace ssh Legacy​

anyscale workspace start Legacy​

anyscale workspace terminate Legacy​

anyscale workspace pull Legacy​

anyscale workspace push Legacy​

anyscale workspace clone Legacy​

anyscale workspace cp Legacy​

Customer-hosted cloud features

Workspaces CLI

`anyscale workspace_v2 create`

Examples

`anyscale workspace_v2 start`

Examples

`anyscale workspace_v2 terminate`

Examples

`anyscale workspace_v2 status`

Examples

`anyscale workspace_v2 wait`

Examples

`anyscale workspace_v2 ssh`

Examples

`anyscale workspace_v2 run_command`

Examples

`anyscale workspace_v2 pull`

Examples

`anyscale workspace_v2 push`

Examples

`anyscale workspace_v2 update`

Examples

`anyscale workspace_v2 get`

Examples

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

Workspaces Models

`WorkspaceConfig`

Fields

Python Methods

Examples

Workspaces CLI Legacy

`anyscale workspace create` Legacy

`anyscale workspace run` Legacy

`anyscale workspace ssh` Legacy

`anyscale workspace start` Legacy

`anyscale workspace terminate` Legacy

`anyscale workspace pull` Legacy

`anyscale workspace push` Legacy

`anyscale workspace clone` Legacy

`anyscale workspace cp` Legacy