Studios SDK tutorial

A Studio is a persistent Lightning AI development environment. Use a Studio for interactive work, dependency setup, exploratory runs, and as a reusable runtime for jobs or MMT runs. Starting a Studio attaches compute. Stopping a Studio releases compute while preserving the Studio resource.

Prerequisites

Install and authenticate:

$ pip install lightning-sdk -U
$ lightning login

The SDK gives you a Python object that can start compute, execute commands, and transfer files. The executable script stops the Studio after any optional commands complete:

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

studio = Studio(
    name=args.studio,
    teamspace=teamspace,
    create_ok=True,
)

studio.start(machine=Machine.from_str(args.machine))
print(f"{studio.name} is {studio.status} on {studio.machine}")

output = studio.run("python --version")
print(output)

studio.upload_file(args.train_file, remote_path="train.py")
train_output = studio.run("python train.py --epochs 1")
print(train_output)

Use run_with_exit_code when failure is part of the control flow and you do not want a non-zero command to raise immediately. The companion script runs this branch only when --run-tests is passed:

if args.run_tests:
    output, exit_code = studio.run_with_exit_code("python -m pytest -q")
    print(output)
    if exit_code != 0:
        raise RuntimeError(f"Tests failed with exit code {exit_code}")

Use run_and_detach for background work where you only need early output and the command should continue in the Studio. The companion script runs this branch only when --detach-training is passed:

if args.detach_training:
    output, exit_code = studio.run_and_detach(
        "python train.py --epochs 10",
        timeout=30,
        check_interval=5,
    )
    print(output)
    print(f"Initial exit code: {exit_code}")

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

$ python python/examples/studios.py --teamspace teamspace --org owner --studio sdk-tutorial-studio
$ python python/examples/studios.py --teamspace teamspace --org owner --studio sdk-tutorial-studio --run-tests

Operational notes

• Studio("name", teamspace=..., create_ok=True) creates the Studio when it does not exist. Use create_ok=False when automation should fail instead of creating a new resource.
• studio.start is blocking while compute is provisioned.
• studio.run requires the Studio to be running and raises if the command exits non-zero.
• Jobs and MMTs can reuse a Studio environment, which is useful when the Studio contains dependencies, code, or secrets configured through Lightning.
• Stop Studios when you do not need active compute.