# Install and authenticate the SDK

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.

> **Note:** `instantml login --api-host ...` only changes the host the login flow contacts. It does not change the SDK host for later scripts; use `INSTANTML_API_BASE_URL` or `base_url=...` for that.

## 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.

| Scope | Allows |
| --- | --- |
| `sdk:ingest` | Create runs, update run status, log metrics, logs, attributes, and rich objects. |
| `artifacts:write` | Create artifact metadata and upload artifact bytes. |
| `artifacts:manage` | Promote or delete artifact aliases, set retention, and delete artifact versions. |
| `imports:write` | Run supported importer routes. |
| `export:read` | Read tenant data, download artifacts, and export bounded data. |
| `usage:read` | Read usage summaries and usage exports. |
| `api_keys:write` | Administer workspace API keys. |
| `runs:control` | Send 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**).

> **Warning:** The plaintext key is shown once at creation. Copy it immediately — after that InstantML only stores its hash.

## Next steps

- [CLI login](/docs/sdk/cli-login.md) — the device-code flow in detail
- [SDK logging](/docs/sdk/logging.md) — create runs and log metrics
- [Buffering, offline replay, and spool mode](/docs/sdk/reliability.md) — durable upload modes
- [Manage API keys in the dashboard](/docs/dashboard/settings-api-keys.md)
- [Quickstart](/docs/quickstart.md) — end-to-end first run

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md) (current page)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)