InstantMLDocs

Install and authenticate the SDK

Install the instantml package and give it credentials with CLI login or an API key.

Open .md

Set up the Python SDK once so every training script can create runs without extra configuration.

Install the SDK

InstantML ships as a Python package, usually imported as im:

bash
python3 -m pip install instantml
python
import instantml as im

Install optional extras only when your scripts need them:

bash
python3 -m pip install "instantml[media]"
python3 -m pip install "instantml[system]"
python3 -m pip install "instantml[all]"

Use media when you create image, audio, or video objects from in-memory data. Use system for psutil/NVML-style system metrics.

Set the API host

The SDK defaults to the hosted API at https://api.instantml.ai. Set an explicit host only when your team has been given a different endpoint:

python
run = im.init(project="cartpole", base_url="https://api.instantml.ai")

Or create a reusable client:

python
client = im.Client(base_url="https://api.instantml.ai", timeout=2.0)
run = client.init(project="cartpole", name="ppo-seed-42")

Authenticate

Hosted InstantML requires an SDK API key. Browser sessions are for the dashboard; they are not SDK credentials. The SDK resolves credentials in this order:

  1. Explicit api_key= argument.
  2. INSTANTML_API_KEY environment variable.
  3. ~/.instantml/credentials, written by instantml login.

For an interactive machine, log in once and the SDK reads the stored credential automatically:

bash
instantml login
instantml whoami

Device-code login mints a credential with the sdk:ingest, artifacts:write, imports:write, and export:read scopes. That covers creating runs, logging metrics, uploading files and checkpoints, running imports, and reading or exporting data. Use a dashboard-created key only when a job needs scopes beyond those, such as artifacts:manage or runs:control.

For CI and remote jobs, set an environment variable:

bash
export INSTANTML_API_KEY="instantml_..."
python3 train.py

Or pass the key explicitly:

python
run = im.init(project="cartpole", api_key="instantml_...")

Top-level im.init(...) fails fast when no credential is found. Lower-level Client(...) objects can be constructed without credentials, but authenticated writes fail once they make a request.

Choose API-key scopes

Create keys from onboarding or the Workspace settings modal (account menu → Workspace settings → API). Use the smallest scope set that matches the job.

ScopeAllows
sdk:ingestCreate runs, update run status, log metrics, logs, attributes, and rich objects.
artifacts:writeCreate artifact metadata and upload artifact bytes.
artifacts:managePromote or delete artifact aliases, set retention, and delete artifact versions.
imports:writeRun supported importer routes.
export:readRead tenant data, download artifacts, and export bounded data.
usage:readRead usage summaries and usage exports.
api_keys:writeAdminister workspace API keys.
runs:controlSend stop requests to running runs.

Project-scoped keys can only access their assigned project. Workspace-scoped keys can access every project allowed by their scopes.

Create keys from the dashboard

Create keys from onboarding or the Workspace settings modal (account menu → Workspace settings → API).

Next steps