Programming Language
- Python :: 3
Lightning SDK for Python
Automate Lightning AI resources from Python scripts, notebooks, and CI.
Quick start • Examples • CLI • Development • Docs
Why Lightning SDK?
Lightning SDK turns Lightning AI into a Python API. Use it to create and manage compute, run training or batch jobs, operate persistent studios, deploy containers, inspect logs, and manage sandboxes without leaving your code.
It is designed for automation first: scripts can resolve teamspace scope, start machines, wait for work to finish, collect output, and tear resources down in the same flow.
Build on Lightning AI, the platform for training, deploying, and scaling AI applications with managed compute, collaborative studios, and production endpoints.
Quick start
Install the package:
pip install lightning-sdk
Authenticate once:
lightning login
Or export credentials from Lightning AI account settings:
export LIGHTNING_API_KEY="..."
Run a sandbox command:
from lightning_sdk.sandbox import Sandbox
sandbox = Sandbox.create(name="python-readme", instance_type="cpu-1")
command = sandbox.run_command("python --version")
print(command.output)
sandbox.delete()
Sandbox-only API keys can also be set with LIGHTNING_SANDBOX_API_KEY or
passed through Sandbox.configure(...).
Examples
Work with a studio
from lightning_sdk import Machine, Studio
studio = Studio("research", teamspace="owner/teamspace", create_ok=True)
studio.start(Machine.CPU)
print(studio.status)
print(studio.run("python --version"))
studio.stop()
Run a container job
from lightning_sdk import Job, Machine
job = Job.run(
name="batch-job",
teamspace="owner/teamspace",
image="python:3.11-slim",
machine=Machine.CPU,
command="python -c 'print(\"hello from a Lightning job\")'",
interruptible=True,
)
job.wait()
print(job.status)
Deploy a container
from lightning_sdk import Deployment, Machine
from lightning_sdk.api.deployment_api import ApiKeyAuth
deployment = Deployment("nginx-demo", teamspace="owner/teamspace")
deployment.start(
image="nginx:latest",
machine=Machine.CPU,
ports=80,
replicas=1,
auth=ApiKeyAuth(),
)
print(deployment.status)
Start sandboxes warm
A warm recipe says what the sandbox should already have done — packages installed, a server listening. Lightning runs it once, snapshots the result, and restores later sandboxes with the same recipe from that snapshot. The recipe is the cache key, so there is no template id to keep in sync.
from lightning_sdk.sandbox import Sandbox, WarmRecipe, wait_for_port
sandbox = Sandbox.create(
name="warm-notebook",
instance_type="cpu-2",
image="docker.io/library/python:3.13",
ports=[8888],
warm=WarmRecipe(
run_cmd=["pip install jupyterlab"],
start_cmd="jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root",
ready_cmd=wait_for_port(8888),
),
)
print(sandbox.warm.state) # "restored" | "building" | "cold"
The first create for a recipe is served cold with the recipe run inline, so you
always get the sandbox you asked for — it is only slower. Baking happens in the
background once a recipe has been asked for more than once. A cold start looks
exactly like a warm one from the outside, so read sandbox.warm.state rather
than assuming, and see examples/warm_sandbox.py
for per-sandbox credentials and warming a Jupyter kernel.
Use persistent sandboxes
from lightning_sdk.sandbox import Sandbox
sandbox = Sandbox.create(
name="persistent-devbox",
instance_type="cpu-1",
persistent=True,
)
sandbox.write_file("/workspace/app.py", "print('hello from a file')\n")
print(sandbox.run_command("python /workspace/app.py").output)
snapshot_id = sandbox.stop()
print(snapshot_id)
CLI
The package installs lightning, lightning-sdk, and sandbox commands. The
examples below use lightning, but the SDK-specific entrypoint accepts the same
arguments.
lightning deployment create nginx-demo \
--teamspace owner/teamspace \
--image nginx:latest \
--machine CPU \
--port 80 \
--replicas 1 \
--api-key-auth
Inspect and stream logs:
lightning deployment inspect nginx-demo --teamspace owner/teamspace --jobs
lightning deployment logs nginx-demo --teamspace owner/teamspace --follow
Delete when finished:
lightning deployment delete nginx-demo --teamspace owner/teamspace --yes
More examples
Runnable examples live in examples/:
| Area | SDK tutorial | CLI tutorial |
|---|---|---|
| studios | studios.rst |
studios_cli.rst |
| jobs | jobs.rst |
jobs_cli.rst |
| multi-machine training | mmts.rst |
mmts_cli.rst |
| teamspaces | teamspaces.rst |
teamspaces_cli.rst |
| sandboxes | sandboxes.rst |
sandboxes_cli.rst |
Development
From the repository root:
pip install -e ./python
From this directory:
pip install -e .
Build docs from the repository root:
uv run --group docs sphinx-build -M html python/docs/sdk python/docs/sdk/build -W --keep-going
uv run --group docs sphinx-build -M html python/docs/cli python/docs/cli/build -W --keep-going
License
Apache-2.0. See ../LICENSE.
Wheel compatibility matrix
Files in release
backoff
click
(>=8.2)
rich-click
docker
fastapi
packaging
pyyaml
requests
rich
six
tqdm
textual
(>=2.0)
urllib3
(<=2.5.0)
uvicorn
websocket-client
(>=1.6)