---
title: Teamspaces SDK tutorial
description: 'A teamspace is the account context for Lightning AI resources. Studios, jobs,'
canonical: 'https://lightning.ai/docs/sdk/stable/examples/teamspaces'
---
# Teamspaces SDK tutorial {#teamspaces-sdk-tutorial}

A teamspace is the account context for Lightning AI resources. Studios, jobs,
MMTs, models, secrets, machines, and cloud accounts are all scoped through a
teamspace. Most workflows start by choosing a teamspace explicitly, then pass
that same context to every SDK object.

## Prerequisites {#prerequisites}

Install and authenticate:

```console
$ pip install lightning-sdk -U
$ lightning login
```

Construct a `Teamspace` when Python code should keep the account context in
one object and pass it to other SDK resources:

```python
teamspace = Teamspace(args.teamspace, org=args.org, user=args.user)

print(f"Teamspace: {teamspace.owner.name}/{teamspace.name}")
print(f"ID: {teamspace.id}")
print(f"Default cloud account: {teamspace.default_cloud_account}")
print(f"Cloud accounts: {', '.join(teamspace.cloud_accounts)}")

for studio in teamspace.studios:
    print(f"Studio {studio.name}: {studio.status}")

for job in teamspace.jobs:
    print(f"Job {job.name}: {job.status} on {job.machine}")

for mmt in teamspace.multi_machine_jobs:
    print(f"MMT {mmt.name}: {mmt.status} across {mmt.num_machines} machines")
```

Use the same object when launching resources so the teamspace cannot silently
come from process config:

```python
teamspace = Teamspace(args.teamspace, org=args.org, user=args.user)
studio = Studio(args.studio, teamspace=teamspace, create_ok=False)

job = Job.run(
    name="teamspace-scoped-job",
    teamspace=teamspace,
    studio=studio,
    machine=Machine.CPU,
    command="python train.py --epochs 1",
)

print(job.link)
```

Manage secrets through the SDK when application code needs to create or update
teamspace-level secret references:

```python
teamspace = Teamspace(args.teamspace, org=args.org, user=args.user)
teamspace.set_secret(
    key="HF_TOKEN_FOR_TUTORIAL",
    value=os.environ["HF_TOKEN"],
    secret_type=SecretType.HF_TOKEN,
)
```

Do not hard-code secret values in source files. Load them from your secret
manager or environment at runtime, then pass them to `set_secret`.

Run the companion script directly when you want to execute the SDK example:

```console
$ python python/examples/teamspaces.py --teamspace teamspace --org owner inspect
$ HF_TOKEN=... python python/examples/teamspaces.py --teamspace teamspace --org owner set-secret
```

## Operational notes {#operational-notes}

- Prefer `Teamspace("name", org="owner")` or `Teamspace("name", user="owner")`
  in SDK code instead of relying on ambient config.
- The SDK raises when it cannot infer whether the owner is a user or
  organization. Passing `org=` or `user=` removes that ambiguity.
- Teamspace resource listings check permissions; a permission error means the
  authenticated identity cannot access that resource family in the teamspace.

---

**Navigation**

- Parent: [Examples](/docs/sdk/2026.11.04/examples.md)