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

Install and authenticate:

$ 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:

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:

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:

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:

$ 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

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.

Was this page helpful?