---
title: Teamspace
description: >-
  A teamspace is a collection of Studios, Clusters, Members and an associated
  Budget.
canonical: 'https://lightning.ai/docs/sdk/stable/api/teamspace'
---
# Teamspace {#teamspace}

### `class lightning_sdk.Teamspace(name=None, org=None, user=None)` {#lightning_sdk.Teamspace}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

A teamspace is a collection of Studios, Clusters, Members and an associated Budget.

Parameters:

*   **name** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – the name of the teamspace, either a bare name or an `owner/teamspace` slug
    
*   **org** (`Union`\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Organization`](/docs/sdk/2026.11.04/api/organization.md#lightning_sdk.Organization "lightning_sdk.organization.Organization"), [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")\]) – the owning organization. Deprecated — pass the owner as part of `name` instead, e.g. `name="owner/teamspace"`.
    
*   **user** (`Union`\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`User`](/docs/sdk/2026.11.04/api/user.md#lightning_sdk.User "lightning_sdk.user.User"), [`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")\]) – the owning user. Deprecated — pass the owner as part of `name` instead, e.g. `name="owner/teamspace"`.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **org** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ [_Organization_](/docs/sdk/2026.11.04/api/organization.md#lightning_sdk.Organization "lightning_sdk.organization.Organization") _|_ _None_)
    
*   **user** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ [_User_](/docs/sdk/2026.11.04/api/user.md#lightning_sdk.User "lightning_sdk.user.User") _|_ _None_)
    

Note

Either user or organization should be specified.

Note

Arguments will be automatically inferred from environment variables if possible, unless explicitly specified

#### `bucket_credentials(connection)` {#lightning_sdk.Teamspace.bucket_credentials}

Get short-lived credentials for the bucket behind a data connection.

The credentials expire, so call this again for a fresh set rather than caching them; `BucketCredentials.expires_at` is the deadline to refresh against. To hand them to a tool that refreshes on its own, see `lightning connection credentials`, which speaks AWS’s `credential_process` protocol.

Parameters:

*   **connection** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Name of the data connection, as it appears in the teamspace drive.
    
*   **connection** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    

Returns:

The credentials, with the region and endpoint to use them against.

Return type:

[BucketCredentials](#lightning_sdk.BucketCredentials "lightning_sdk.BucketCredentials")

Raises:

[**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the teamspace has no data connection with that name.

#### `create_agent(name, api_key, base_url, model, org_id='', prompt_template='', description='', prompt_suggestions=None, file_uploads_enabled=None)` {#lightning_sdk.Teamspace.create_agent}

Create a new AI agent backed by a custom model endpoint.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Display name for the agent.
    
*   **api\_key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – API key used to authenticate requests to the model endpoint.
    
*   **base\_url** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Base URL of the model endpoint (e.g. an OpenAI-compatible server).
    
*   **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Model identifier to use (e.g. `"gpt-4o"`).
    
*   **org\_id** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Optional organization ID to associate with the agent. Defaults to `""`.
    
*   **prompt\_template** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – System prompt template shown to the model. Defaults to `""`.
    
*   **description** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Human-readable description of the agent. Defaults to `""`.
    
*   **prompt\_suggestions** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`List`](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]\]) – Suggested user prompts shown in the chat UI. Defaults to None.
    
*   **file\_uploads\_enabled** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")\]) – Whether the agent accepts file uploads from users. Defaults to None.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **api\_key** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **base\_url** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **model** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **org\_id** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **prompt\_template** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **description** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **prompt\_suggestions** ([_List_](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")_\[_[_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")_\]_ _|_ _None_)
    
*   **file\_uploads\_enabled** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") _|_ _None_)
    

Returns:

The newly created agent.

Return type:

[Agent](/docs/sdk/2026.11.04/api/agent.md#lightning_sdk.Agent "lightning_sdk.Agent")

#### `delete_model(name)` {#lightning_sdk.Teamspace.delete_model}

Delete a model from the model store.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Name tag of the model to delete. Can optionally also contain a version tag separated by a colon, e.g. ‘entity/modelname:v1’.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `delete_secret(key)` {#lightning_sdk.Teamspace.delete_secret}

Delete a generic encrypted secret from the teamspace.

Parameters:

*   **key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Secret name. Must start with a letter or underscore and contain only alphanumeric characters and underscores.
    
*   **key** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    

Raises:

[**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the key is invalid or no generic secret with that name exists.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `download_file(remote_path, file_path=None, cloud_account=None)` {#lightning_sdk.Teamspace.download_file}

Download a file from the Teamspace drive to a local path.

Parameters:

*   **remote\_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Path of the file inside the Teamspace drive.
    
*   **file\_path** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Local destination path. Defaults to `remote_path`.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Cloud account to use. Defaults to `None`.
    
*   **remote\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **file\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `download_folder(remote_path, target_path=None, cloud_account=None)` {#lightning_sdk.Teamspace.download_folder}

Download a directory from the Teamspace drive to a local path.

Parameters:

*   **remote\_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Path of the directory inside the Teamspace drive.
    
*   **target\_path** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Local destination directory. Defaults to `remote_path`.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Cloud account to use. Defaults to `None`.
    
*   **remote\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **target\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `download_model(name, download_dir=None, progress_bar=True)` {#lightning_sdk.Teamspace.download_model}

Download a checkpoint from the model store.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Name tag of the model to download. Can optionally also contain a version tag separated by a colon, e.g. ‘modelname:v1’.
    
*   **download\_dir** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – A path to directory where the model should be downloaded. Defaults to the current working directory.
    
*   **progress\_bar** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – Whether to show a progress bar for the download.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **download\_dir** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **progress\_bar** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    

Return type:

[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

Returns:

The absolute path to the downloaded model file or folder.

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If no model name is provided.
    
*   [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – If the model upload is not yet complete or no files were downloaded.
    

#### `list_files(remote_path='', recursive=False, cloud_account=None)` {#lightning_sdk.Teamspace.list_files}

List the entries of a directory in the Teamspace drive.

Parameters:

*   **remote\_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Path of the directory inside the Teamspace drive. Defaults to the drive root, which lists its top-level folders (`studios`, `jobs`, …).
    
*   **recursive** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – When `True`, descend into subdirectories. Each returned path is then relative to `remote_path`.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Cloud account to use. Defaults to `None`.
    
*   **remote\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **recursive** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Returns:

One entry per file or folder, in the order the server returns them.

Return type:

List\[[FileEntry](#lightning_sdk.FileEntry "lightning_sdk.FileEntry")\]

#### `list_jobs(tags=None)` {#lightning_sdk.Teamspace.list_jobs}

The standalone and multi-machine jobs in this teamspace, optionally filtered by tag.

Parameters:

*   **tags** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]\]) – Only return jobs carrying at least one of these tags. `None` returns every job.
    
*   **tags** ([_Sequence_](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")_\[_[_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")_\]_ _|_ _None_)
    

Returns:

The matching Jobs, standalone ones first.

Return type:

[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[Job](/docs/sdk/2026.11.04/api/job.md#lightning_sdk.Job "lightning_sdk.Job"), …\]

Raises:

*   [**PermissionError**](https://docs.python.org/3/builtins/exceptions.html#PermissionError "(in Python v3.15)") – If the authenticated user cannot access Jobs in this teamspace.
    
*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the teamspace has no tag by one of the given names.
    

#### `list_machines(cloud_account=None, machine=None)` {#lightning_sdk.Teamspace.list_machines}

List available machines across cloud accounts.

Parameters:

*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – The cloud account from which to list available machines. If None, uses LIGHTNING\_CLUSTER\_ID environment variable. If that’s also None, queries all global cloud accounts.
    
*   **machine** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Specific machine name to filter by. If provided, only returns that machine type. Must be a valid Machine enum value.
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **machine** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Return type:

[`List`](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")\[[`Machine`](/docs/sdk/2026.11.04/api/machine.md#lightning_sdk.Machine "lightning_sdk.machine.Machine")\]

Returns:

List of available machines, excluding out-of-capacity machines.

Raises:

*   [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – If no cloud account can be resolved.
    
*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the provided machine name is not a valid Machine value.
    

#### `list_model_versions(name)` {#lightning_sdk.Teamspace.list_model_versions}

List all versions of a model in the model store.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – The model name to list versions for. Must not include a version tag (no colon).
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    

Returns:

All available versions of the specified model.

Return type:

List\[V1ModelVersionArchive\]

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `name` contains a colon (version tag).
    
*   [**PermissionError**](https://docs.python.org/3/builtins/exceptions.html#PermissionError "(in Python v3.15)") – If the authenticated user cannot access Models in this teamspace.
    

#### `list_models()` {#lightning_sdk.Teamspace.list_models}

List all models in the model store.

Returns:

All models stored in this teamspace’s model store.

Return type:

List\[V1Model\]

#### `new_connection(name, source, connection_type, writable=True, cloud_account=None, region=None)` {#lightning_sdk.Teamspace.new_connection}

Add an existing data source to this Teamspace.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – the name under which your data will be available in this Teamspace
    
*   **source** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – the source spec of your data. Format depends on the type of data to connect. For EFS, this should be the filsystem id
    
*   **connection\_type** ([`ConnectionType`](#lightning_sdk.ConnectionType "lightning_sdk.teamspace.ConnectionType")) – the kind of data to connect to this Teamspace
    
*   **writable** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – whether to support write-back to this data source. If False, the data is connected as read-only
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – which cloud-account to connect to the data source to. If not specified, will retrieve the cloud-account that matches the required provider type starting with private cloud accounts and falling back to public if necessary.
    
*   **region** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – which provider region this data is in. Required for some connection types only.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **source** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **connection\_type** ([_ConnectionType_](#lightning_sdk.ConnectionType "lightning_sdk.teamspace.ConnectionType"))
    
*   **writable** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **region** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Raises:

[**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If region is not specified for EFS connections, or if the resolved cloud account is not found.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `new_folder(name, location=None, cloud_account=None)` {#lightning_sdk.Teamspace.new_folder}

Create a new folder in this Teamspace.

Parameters:

*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – The name of the folder. Folders will be accesible under /teamspace/folders/<name>
    
*   **location** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`FolderLocation`](#lightning_sdk.FolderLocation "lightning_sdk.teamspace.FolderLocation")\]) – The location of the folder. Defaults to cloud agnostic.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – The cloud account to create the folder in. Not used for cloud agnostic folders.
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **location** ([_FolderLocation_](#lightning_sdk.FolderLocation "lightning_sdk.teamspace.FolderLocation") _|_ _None_)
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Raises:

[**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the specified cloud account cannot be found in this teamspace.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `set_secret(key, value, secret_type=SecretType.GENERIC)` {#lightning_sdk.Teamspace.set_secret}

Set an encrypted secret for the teamspace.

Parameters:

*   **key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Secret name. Must start with a letter or underscore and contain only alphanumeric characters and underscores.
    
*   **value** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – The secret value to store.
    
*   **secret\_type** (`Union`\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`SecretType`](#lightning_sdk.SecretType "lightning_sdk.api.teamspace_api.SecretType")\]) – The type of secret, either a `SecretType` member or its string value. Defaults to `SecretType.GENERIC`. Use `SecretType.HF_TOKEN` (or `"hf_token"`) to tag the secret as a HuggingFace access token so it can be referenced via `Deployment.start(hf_token_secret=...)`. The type is only applied when the secret is created; updating an existing secret leaves its type unchanged.
    
*   **key** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **value** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **secret\_type** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ [_SecretType_](#lightning_sdk.SecretType "lightning_sdk.api.teamspace_api.SecretType"))
    

Raises:

[**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `key` contains invalid characters or `secret_type` is invalid.

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `upload_file(file_path, remote_path=None, progress_bar=True, cloud_account=None)` {#lightning_sdk.Teamspace.upload_file}

Upload a file to the Teamspace drive.

Parameters:

*   **file\_path** (`Union`\[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Local path of the file to upload.
    
*   **remote\_path** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Destination path inside the Teamspace drive. Defaults to the file’s basename.
    
*   **progress\_bar** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – Whether to display a progress bar. Defaults to `True`.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Cloud account to use for storage. Defaults to the teamspace default.
    
*   **file\_path** ([_Path_](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") _|_ [_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **remote\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **progress\_bar** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `upload_folder(folder_path, remote_path=None, progress_bar=True, cloud_account=None)` {#lightning_sdk.Teamspace.upload_folder}

Upload a local directory to the Teamspace drive.

Parameters:

*   **folder\_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Local directory to upload.
    
*   **remote\_path** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Destination directory inside the Teamspace drive.
    
*   **progress\_bar** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – Whether to display a progress bar. Defaults to `True`.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Cloud account to use for storage. Defaults to the teamspace default.
    
*   **folder\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **remote\_path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **progress\_bar** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If `folder_path` is `None`.
    
*   [**NotADirectoryError**](https://docs.python.org/3/builtins/exceptions.html#NotADirectoryError "(in Python v3.15)") – If `folder_path` is a file or does not exist.
    

Return type:

[`None`](https://docs.python.org/3/builtins/constants.html#None "(in Python v3.15)")

#### `upload_model(path, name, version=None, cloud_account=None, progress_bar=True, metadata=None, experiment=None)` {#lightning_sdk.Teamspace.upload_model}

Upload a local checkpoint file to the model store.

If a previous upload for the same model was interrupted, it is automatically resumed: already-uploaded files are skipped and only the remaining files are uploaded under the same model version.

Parameters:

*   **path** (`Union`\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)"), [`List`](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")\[`Union`\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")\]\]\]) – Path to the model file or folder to upload.
    
*   **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")) – Name tag of the model to upload.
    
*   **version** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – Version tag of the model to upload. If not provided, the `vX` version will be used where X is running index.
    
*   **cloud\_account** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]) – The name of the cloud account to store the Model in. If not provided, the default cloud account for the Teamspace will be used.
    
*   **progress\_bar** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")) – Whether to show a progress bar for the upload.
    
*   **metadata** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)")\]) – Metadata to attach to the model. Can be a dictionary.
    
*   **experiment** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Experiment`](/docs/sdk/2026.11.04/api/experiment.md#lightning_sdk.api.utils.Experiment "lightning_sdk.api.utils.Experiment")\]) – The experiment producing this model.
    
*   **path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ [_Path_](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)") _|_ [_List_](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")_\[_[_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ [_Path_](https://docs.python.org/3/library/pathlib.html#pathlib.Path "(in Python v3.15)")_\]_)
    
*   **name** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **version** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **progress\_bar** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **metadata** ([_dict_](https://docs.python.org/3/builtins/stdtypes.html#dict "(in Python v3.15)") _|_ _None_)
    
*   **experiment** ([_Experiment_](/docs/sdk/2026.11.04/api/experiment.md#lightning_sdk.api.utils.Experiment "lightning_sdk.api.utils.Experiment") _|_ _None_)
    

Returns:

An object describing the uploaded model (name, version, teamspace, cloud\_account).

Return type:

[UploadedModelInfo](/docs/sdk/2026.11.04/api/models.md#lightning_sdk.models.UploadedModelInfo "lightning_sdk.models.UploadedModelInfo")

Raises:

*   [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If no path or name is provided, or if metadata is not a dict.
    
*   [**FileNotFoundError**](https://docs.python.org/3/builtins/exceptions.html#FileNotFoundError "(in Python v3.15)") – If the path contains no files.
    
*   [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError "(in Python v3.15)") – If multiple paths resolve to conflicting relative paths.
    
*   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If metadata is not a dictionary.
    

#### `property cloud_account_objs: List[V1ProjectClusterBinding]` {#lightning_sdk.Teamspace.cloud_account_objs}

All cloud accounts associated with that teamspace.

Returns:

The raw cloud account binding objects for this teamspace.

Return type:

List\[V1ProjectClusterBinding\]

#### `property cloud_accounts: List[str]` {#lightning_sdk.Teamspace.cloud_accounts}

All cloud accounts associated with that teamspace.

Returns:

The cloud account names for this teamspace.

Return type:

List\[[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]

#### `property clusters: List[str]` {#lightning_sdk.Teamspace.clusters}

All clusters associated with that teamspace.

Returns:

The cluster names for this teamspace. Deprecated — use [`cloud_accounts`](#lightning_sdk.Teamspace.cloud_accounts "lightning_sdk.Teamspace.cloud_accounts") instead.

Return type:

List\[[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]

#### `property default_cloud_account: str | None` {#lightning_sdk.Teamspace.default_cloud_account}

The default cloud account for this teamspace.

Falls back to the owning organization’s preferred cloud account when the teamspace has none set.

Returns:

The preferred cloud account ID, or None if not configured.

Return type:

[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") | None

#### `property id: str` {#lightning_sdk.Teamspace.id}

The teamspace’s ID.

Returns:

The unique identifier of this teamspace.

Return type:

[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

#### `property jobs: Tuple[Job, ...]` {#lightning_sdk.Teamspace.jobs}

All standalone and multi-machine jobs in this teamspace.

Returns:

Every Job belonging to this teamspace.

Return type:

[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[Job](/docs/sdk/2026.11.04/api/job.md#lightning_sdk.Job "lightning_sdk.Job"), …\]

Raises:

[**PermissionError**](https://docs.python.org/3/builtins/exceptions.html#PermissionError "(in Python v3.15)") – If the authenticated user cannot access Jobs in this teamspace.

#### `property multi_machine_jobs: Tuple[MMT, ...]` {#lightning_sdk.Teamspace.multi_machine_jobs}

All multi-machine training jobs in this teamspace.

Returns:

Every MMT job belonging to this teamspace.

Return type:

[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[MMT](/docs/sdk/2026.11.04/api/mmt.md#lightning_sdk.MMT "lightning_sdk.MMT"), …\]

Raises:

[**PermissionError**](https://docs.python.org/3/builtins/exceptions.html#PermissionError "(in Python v3.15)") – If the authenticated user cannot access Jobs in this teamspace.

#### `property name: str` {#lightning_sdk.Teamspace.name}

The teamspace’s name.

Returns:

The name of this teamspace.

Return type:

[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")

#### `property owner: Owner` {#lightning_sdk.Teamspace.owner}

The teamspace’s owner.

Returns:

The owning [`Owner`](/docs/sdk/2026.11.04/api/owner.md#lightning_sdk.owner.Owner "lightning_sdk.owner.Owner") (user or org).

Return type:

[Owner](/docs/sdk/2026.11.04/api/owner.md#lightning_sdk.owner.Owner "lightning_sdk.owner.Owner")

#### `property secrets: Dict[str, str]` {#lightning_sdk.Teamspace.secrets}

All (encrypted) secrets for the teamspace.

Note

Once created, the secret values are encrypted and cannot be viewed here anymore.

Returns:

A mapping of secret names to their (encrypted) values.

Return type:

Dict\[[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")\]

#### `property start_studios_on_interruptible: bool` {#lightning_sdk.Teamspace.start_studios_on_interruptible}

Whether new Studios in this teamspace start on interruptible (spot) instances by default.

Returns:

True if Studios default to interruptible instances.

Return type:

[bool](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")

#### `property studios: List[Studio]` {#lightning_sdk.Teamspace.studios}

All studios within that teamspace.

Returns:

Every Studio belonging to this teamspace.

Return type:

List\[[Studio](/docs/sdk/2026.11.04/api/studio.md#lightning_sdk.Studio "lightning_sdk.Studio")\]

#### `property tags: Tuple[str, ...]` {#lightning_sdk.Teamspace.tags}

Every job tag defined in this teamspace.

Returns:

The tag names, as the platform stores them.

Return type:

[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")\[[str](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), …\]

### `class lightning_sdk.BucketCredentials(access_key_id, secret_access_key, session_token=None, expires_at=None, region=None, endpoint=None)` {#lightning_sdk.BucketCredentials}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

Short-lived credentials for the bucket behind a data connection.

These expire — usually within the hour — so they are meant to be fetched when needed rather than held. `expires_at` is the deadline to refresh against, and is `None` only for connections backed by static keys, which do not expire.

`region` and `endpoint` are part of the answer, not decoration. Inside a Studio the default AWS profile can point at Lightning Storage, and botocore will apply that profile’s endpoint to any client built without one — which sends an AWS request to Cloudflare and gets it rejected as `InvalidAccessKeyId`. Pass these through rather than letting a client resolve its own.

Parameters:

*   **access\_key\_id** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **secret\_access\_key** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **session\_token** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **expires\_at** ([_datetime_](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") _|_ _None_)
    
*   **region** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **endpoint** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    

#### `to_credential_process()` {#lightning_sdk.BucketCredentials.to_credential_process}

Render as the JSON payload AWS’s `credential_process` expects.

Any tool that understands that setting — the AWS CLI, boto3, rclone, s5cmd, the Go and Java SDKs — will re-run the process to refresh once `Expiration` passes, which is what makes the short lifetime survivable without per-tool support.

`Expiration` is omitted for credentials that never expire, which AWS reads as “cache indefinitely”.

Return type:

[`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict "(in Python v3.15)")\[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]

Returns:

The credential payload, ready to be serialised to stdout as JSON.

### `class lightning_sdk.FileEntry(path, is_dir, size=None, cloud_account=None, last_modified=None)` {#lightning_sdk.FileEntry}

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

One entry in a teamspace drive listing.

Parameters:

*   **path** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))
    
*   **is\_dir** ([_bool_](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))
    
*   **size** ([_int_](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") _|_ _None_)
    
*   **cloud\_account** ([_str_](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") _|_ _None_)
    
*   **last\_modified** ([_datetime_](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") _|_ _None_)
    

#### `path` {#lightning_sdk.FileEntry.path}

Path relative to the folder that was listed.

#### `is_dir` {#lightning_sdk.FileEntry.is_dir}

Whether the entry is a folder rather than a file.

#### `size` {#lightning_sdk.FileEntry.size}

Size in bytes, or `None` for folders.

#### `cloud_account` {#lightning_sdk.FileEntry.cloud_account}

Cloud account holding the file, when the server reports one.

#### `last_modified` {#lightning_sdk.FileEntry.last_modified}

When the file was last written, when the server reports it.

#### `property name: str` {#lightning_sdk.FileEntry.name}

The entry’s own name, without any leading folders.

### `class lightning_sdk.SecretType(*values)` {#lightning_sdk.SecretType}

Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.15)")

Type of an encrypted secret.

`GENERIC` secrets are exposed as environment variables. `HF_TOKEN` tags a secret as a HuggingFace access token so it can be referenced when deploying gated or private HuggingFace models (`Deployment.start(hf_token_secret=...)`).

#### `GENERIC = 'generic'` {#lightning_sdk.SecretType.GENERIC}

#### `HF_TOKEN = 'hf_token'` {#lightning_sdk.SecretType.HF_TOKEN}

### `class lightning_sdk.ConnectionType(*values)` {#lightning_sdk.ConnectionType}

Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.15)")

Type of external data source that can be connected to a Teamspace.

#### `EFS = 'EFS'` {#lightning_sdk.ConnectionType.EFS}

#### `FILESTORE = 'FILESTORE'` {#lightning_sdk.ConnectionType.FILESTORE}

#### `GCS = 'GCS'` {#lightning_sdk.ConnectionType.GCS}

#### `S3 = 'S3'` {#lightning_sdk.ConnectionType.S3}

### `class lightning_sdk.FolderLocation(*values)` {#lightning_sdk.FolderLocation}

Bases: [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum "(in Python v3.15)")

Cloud provider location for a Teamspace folder.

#### `AWS = 'AWS'` {#lightning_sdk.FolderLocation.AWS}

#### `CLOUD_AGNOSTIC = 'CLOUD_AGNOSTIC'` {#lightning_sdk.FolderLocation.CLOUD_AGNOSTIC}

#### `GCP = 'GCP'` {#lightning_sdk.FolderLocation.GCP}

---

**Navigation**

- Parent: [API Reference](/docs/sdk/2026.11.04/api.md)