Studio

Bases: object

A single Lightning AI Studio.

Allows to fully control a studio, including retrieving the status, running commands and switching machine types.

Parameters:

• name (Optional[str]) – the name of the studio

• teamspace (Union[str, Teamspace, None]) – the name of the teamspace the studio is contained by. Accepts a bare name or an owner/teamspace slug.

• org (Union[str, Organization, None]) – the name of the organization owning the the teamspace in case it is owned by an org. Deprecated — pass the owner as part of teamspace instead, e.g. teamspace="owner/teamspace".

• user (Union[str, User, None]) – the name of the user owning the the teamspace in case it is owned directly by a user instead of an org. Deprecated — pass the owner as part of teamspace instead, e.g. teamspace="owner/teamspace".

• cloud (Union[CloudProvider, str, None]) – Cloud provider or cloud account to create the studio on.

• create_ok (bool) – whether the studio will be created if it does not yet exist. Defaults to True

• studio_type (Optional[str]) – Type of studio to create: a base studio template id or name. Defaults to the current studio’s template when creating from inside a Studio in the same teamspace, otherwise to the first enabled template. Only effective during initial creation; ignored for existing studios.

• name (str | None)

• teamspace (str | Teamspace | None)

• org (str | Organization | None)

• user (str | User | None)

• cloud (CloudProvider | str | None)

• create_ok (bool)

• source (str | None)

• disable_secrets (bool)

• studio_type (str | None)

add_ports(ports)

Add one or more ports to the studio and return their endpoints.

Parameters:

• ports (Union[int, List[int], Dict[str, int]]) – Port to add. Can be: - int: Single port (e.g., 8080) - List[int]: Multiple ports () - dict[str, int]: Named ports (e.g., {“web”: 8080})

• ports (int | List[int] | Dict[str, int])

Return type:

List[V1Endpoint]

Returns:

Endpoints for the added ports. Each entry exposes name, ports, and urls attributes.

create_assistant(name, port)

Create a Lightning AI assistant backed by a service running on this Studio.

Parameters:

• name (str) – Display name for the assistant.

• port (int) – The port on this Studio that serves the assistant endpoint.

• name (str)

• port (int)

Return type:

None

Returns:

None; the assistant ID is stored on the instance for later use.

delete()

Deletes the current Studio.

Return type:

None

delete_env(key)

Delete one directly configured Studio environment variable.

Parameters:

• key (str) – Name of the environment variable to delete.

• key (str)

Raises:

ValueError – If the name is invalid or is not directly configured.

Return type:

None

download_file(remote_path, file_path=None)

Downloads a file from the Studio to a given target path.

Parameters:

• remote_path (str) – Path of the file inside the Studio to download.

• file_path (Optional[str]) – Local destination path. Defaults to remote_path.

• remote_path (str)

• file_path (str | None)

Return type:

None

download_folder(remote_path, target_path=None)

Downloads a folder from the Studio to a given target path.

Parameters:

• remote_path (str) – Path of the directory inside the Studio to download.

• target_path (Optional[str]) – Local destination directory. Defaults to remote_path.

• remote_path (str)

• target_path (str | None)

Return type:

None

duplicate(target_teamspace=None, machine=Machine(name='CPU', slug='cpu-4', instance_type=None, family='CPU', accelerator_count=4, cost=None, interruptible_cost=None, provider=None, wait_time=None, interruptible_wait_time=None, _include_in_cli=True), name=None)

Duplicates the existing Studio.

Parameters:

• target_teamspace (Union[str, Teamspace, None]) – the teamspace to duplicate the studio to. Must have the same owner as the source teamspace. If not provided, defaults to current teamspace.

• machine (Machine) – the machine to start the duplicated studio on. Defaults to CPU

• target_teamspace (str | Teamspace | None)

• machine (Machine)

• name (str | None)

Returns:

The newly created duplicate Studio.

Return type:

Studio

Raises:

ValueError – If the target teamspace cannot be resolved.

list_ports()

List ports that are exposed in the Studio.

Returns:

The currently exposed port endpoints.

Return type:

List[V1Endpoint]

rename(new_name)

Renames the current Studio to the provided new name.

Parameters:

• new_name (str) – The new display name for the Studio.

• new_name (str)

Return type:

None

run(*commands)

Runs given commands on the Studio while returning only the output.

Parameters:

• commands (str) – the commands to run on the Studio in sequence.

• commands (str)

Returns:

The combined stdout output of the commands.

Return type:

str

Raises:

RuntimeError – If any command exits with a non-zero exit code.

run_and_detach(*commands, timeout=10, check_interval=1)

Runs given commands on the Studio and returns immediately.

The command will continue to run in the background.

Parameters:

• *commands (str) – The shell commands to execute in sequence.

• timeout (float) – Wait for this many seconds for the command to finish. Defaults to 10.

• check_interval (float) – Poll the command status every this many seconds. Defaults to 1.

• commands (str)

• timeout (float)

• check_interval (float)

Return type:

Tuple[str, Optional[int]]

Returns:

Tuple of (output, exit_code) collected up to the timeout.

Raises:

• ValueError – If check_interval is greater than timeout.

• RuntimeError – If the Studio is not currently running.

run_job(name, machine, command, env=None, interruptible=False, reuse_snapshot=True, max_run_attempts=None, keep_minutes=None)

Run async workloads using the compute environment from your studio.

Parameters:

• name (str) – The name of the job. Needs to be unique within the teamspace.

• machine (Union[Machine, str]) – The machine type to run the job on.

• command (str) – The command to run inside your job.

• env (Optional[Dict[str, str]]) – Environment variables to set inside the job.

• interruptible (bool) – Whether the job should run on interruptible instances. They are cheaper but can be preempted.

• reuse_snapshot (bool) – Whether the job should reuse a Studio snapshot when multiple jobs for the same Studio are submitted. Turning this off may result in longer job startup times. Defaults to True.

• max_run_attempts (Optional[int]) – Max number of run attempts for this job. None or 0 means unset (backend default). 1 means a single attempt (no retries).

• keep_minutes (Optional[int]) – Minutes to keep the machine after the job stops. None or 0 releases the machine immediately.

• name (str)

• machine (Machine | str)

• command (str)

• env (Dict[str, str] | None)

• interruptible (bool)

• reuse_snapshot (bool)

• max_run_attempts (int | None)

• keep_minutes (int | None)

Returns:

The submitted Job instance.

Return type:

Job

run_mmt(name, num_machines, machine, command, env=None, interruptible=False, max_run_attempts=None, keep_minutes=None)

Run async workloads using the compute environment from your studio.

Parameters:

• name (str) – The name of the job. Needs to be unique within the teamspace.

• num_machines (int) – The number of machines to run on.

• machine (Union[Machine, str]) – The machine type to run the job on.

• command (str) – The command to run inside your job.

• env (Optional[Dict[str, str]]) – Environment variables to set inside the job.

• interruptible (bool) – Whether the job should run on interruptible instances. They are cheaper but can be preempted.

• max_run_attempts (Optional[int]) – Max number of run attempts for this multi-machine job. None or 0 means unset (legacy, no retries); 1 means a single attempt (no retries). When greater than 1 the RECREATE_ALL_NODES fault tolerance strategy is set automatically on the multi-machine job body. Set at the multi-machine job level, not on the per-machine JobSpec.

• keep_minutes (Optional[int]) – Minutes to keep the machines after the job stops. None or 0 releases the machines immediately.

• name (str)

• num_machines (int)

• machine (Machine | str)

• command (str)

• env (Dict[str, str] | None)

• interruptible (bool)

• max_run_attempts (int | None)

• keep_minutes (int | None)

Returns:

The submitted MMT instance.

Return type:

MMT

run_with_exit_code(*commands)

Runs given commands on the Studio while returning output and exit code.

Parameters:

• commands (str) – the commands to run on the Studio in sequence.

• commands (str)

Returns:

A tuple of (output, exit_code).

Return type:

Tuple[str, int]

Raises:

RuntimeError – If the Studio is not currently running.

set_env(new_env, partial=True)

Set the environment variables for the Studio.

Parameters:

• new_env (Dict[str, str]) – The new environment variables to set.

• partial (bool) – Whether to only set the environment variables that are provided. If False, existing environment variables that are not in new_env will be removed. If True, existing environment variables that are not in new_env will be kept.

• new_env (Dict[str, str])

• partial (bool)

Return type:

None

start(machine=None, interruptible=None, max_runtime=None)

Starts a Studio on the specified machine type (default: CPU-4).

Parameters:

• machine (Union[Machine, str, None]) – the machine type to start the studio on. Defaults to CPU-4

• interruptible (Optional[bool]) – whether to use interruptible machines

• max_runtime (Optional[int]) – the duration (in seconds) for which to allocate the machine. Irrelevant for most machines, required for some of the top-end machines on GCP. If in doubt, set it. Won’t have an effect on machines not requiring it. Defaults to 3h

• machine (Machine | str | None)

• interruptible (bool | None)

• max_runtime (int | None)

Raises:

• RuntimeError – If the Studio is already running on a different machine or is not stopped.

• RuntimeError – If the requested machine has no available capacity.

• RuntimeError – If the started instance fails or stops before becoming ready.

Warns:

UserWarning – If the requested machine is not a known machine type for the selected cloud account. It is treated as a custom instance type and passed through as-is.

Return type:

None

stop()

Stops a running Studio.

Raises:

RuntimeError – If the Studio is not currently running or pending.

Return type:

None

switch_machine(machine, interruptible=False, cloud_provider=None)

Switches machine to the provided machine type/.

Parameters:

• machine (Union[Machine, str]) – the new machine type to switch to

• interruptible (bool) – determines whether to switch to an interruptible instance

• cloud_provider (Optional[CloudProvider]) – the cloud provider to switch to, has no effect if the Studio is not on Lightning Cloud

• machine (Machine | str)

• interruptible (bool)

• cloud_provider (CloudProvider | None)

Return type:

None

Note

this call is blocking until the new machine is provisioned

Raises:

RuntimeError – If the Studio is not currently running.

Parameters:

• machine (Machine | str)

• interruptible (bool)

• cloud_provider (CloudProvider | None)

Return type:

None

upload_file(file_path, remote_path=None, progress_bar=True)

Uploads a given file to a remote path on the Studio.

Parameters:

• file_path (str) – Local path of the file to upload.

• remote_path (Optional[str]) – Destination path inside the Studio. Defaults to the file’s basename.

• progress_bar (bool) – Whether to display a progress bar. Defaults to True.

• file_path (str)

• remote_path (str | None)

• progress_bar (bool)

Return type:

None

upload_folder(folder_path, remote_path=None, progress_bar=True)

Uploads a given folder to a remote path on the Studio.

Parameters:

• folder_path (str) – Local directory to upload.

• remote_path (Optional[str]) – Destination directory inside the Studio. Defaults to preserving the relative structure.

• progress_bar (bool) – Whether to display a progress bar. Defaults to True.

• folder_path (str)

• remote_path (str | None)

• progress_bar (bool)

Raises:

• ValueError – If folder_path is None.

• NotADirectoryError – If folder_path is a file or does not exist.

Return type:

None

property auto_shutdown: bool

Whether auto-sleep is enabled. Deprecated — use auto_sleep instead.

Returns:

True if auto-sleep is currently enabled.

Return type:

bool

property auto_shutdown_time: int

Idle timeout in seconds before auto-sleep. Deprecated — use auto_sleep_time instead.

Returns:

The current idle timeout in seconds.

Return type:

int

property auto_sleep: bool

Returns if a Studio has auto-sleep enabled.

Returns:

True if auto-sleep is enabled for this Studio.

Return type:

bool

property auto_sleep_time: int

Returns the time in seconds a Studio has to be idle for auto-sleep to kick in (if enabled).

Returns:

Idle timeout in seconds before auto-sleep activates.

Return type:

int

property cloud_account: str

The cloud account ID this Studio is associated with.

Returns:

The cloud account (cluster) ID.

Return type:

str

property cluster: str

Returns the cluster the Studio is running on.

Returns:

The cloud account (cluster) ID.

Return type:

str

property env: Dict[str, str]

All environment variables currently set on this Studio.

Returns:

Mapping of environment variable names to their values.

Return type:

dict[str, str]

property id: str

The studio’s unique identifier.

property interruptible: bool | None

Returns whether the Studio is running on a interruptible instance.

Returns:

True if the Studio is on an interruptible instance, None if not running.

Return type:

bool

property machine: Machine | None

Returns the current machine type the Studio is running on.

Returns:

The active Machine, or None if not running.

Return type:

Optional[Machine]

property name: str

Returns the name of the studio.

Returns:

The studio name.

Return type:

str

property owner: Owner

Returns the name of the owner (either user or org).

Returns:

The owning Owner (user or org).

Return type:

Owner

property placement_group_id: str | None

The placement group identifier for this Studio’s current compute, if assigned.

property public_ip: str | None

Returns the public IP address of the machine the Studio is running on.

Returns:

The public IP, or None if unavailable.

Return type:

Optional[str]

property status: Status

Returns the Status of the Studio.

Can be one of { NotCreated | Pending | Running | Stopping | Stopped | Failed }

Returns:

The current Status of the Studio.

Return type:

Status

property teamspace: Teamspace

Returns the name of the Teamspace.

Returns:

The Teamspace this Studio belongs to.

Return type:

Teamspace