> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hardlightsim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> End-to-end onboarding from API key to first artifact download.

## Outcome

After this flow, you can:

* create a scoped service key
* submit simulation jobs with `pip install hardsim`
* download artifacts from successful jobs
* inspect diagnostics artifacts from failed jobs

## 1) Create Service API Key

1. Open Hardlight dashboard.
2. Go to `API` page.
3. Click `Create key`.
4. Copy the key immediately (shown once).

Use only `hls_live_*` service keys for SDK usage.

## 2) Install SDK

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade hardsim
```

## 3) Configure Environment

```bash theme={null}
export HARDSIM_API_URL=https://api-sim.hardlightsim.com
export HARDSIM_API_KEY=hls_live_your_service_key
```

## 4) Run A Job

```python theme={null}
import hardsim as hs

client = hs.HardsimClient.from_env()

robot_asset_id = client.upload_input_asset("./assets/franka.urdf", asset_kind="robot")
scene_asset_id = client.upload_input_asset("./assets/cabinet_scene.usd", asset_kind="scene")

job = client.submit_assets(
    robot_asset_id=robot_asset_id,
    scene_asset_id=scene_asset_id,
    robot_asset_type="urdf",
    num_envs=8,
    steps=128,
    scene_id="franka_cabinet_oige_v1",
    control={"task_mode": "fr3_pick_lift_block_v1", "fix_base": True},
)

result = client.wait(job.job_id, poll_interval_s=2.0, timeout_s=900.0, raise_on_error=False)
paths = client.download(job.job_id, "./outputs")

print(job.job_id, result["status"], paths)
```

This keeps raw storage URIs out of normal user flow and makes reruns easier.

For advanced task-package workloads, see [Isaac Lab Jobs](./isaac-lab-jobs).

## 5) Status From Terminal (Anytime)

```python theme={null}
# Manual status check
print(client.status(job.job_id))

# Live stream (full watch, configurable timeout)
client.watch_job(job.job_id, poll_interval_s=2.0, timeout_s=36000)
```

## Common Errors

* `403 Plan not entitled for simulation jobs`: plan is not allowed by entitlement policy.
* `402 Insufficient simulation credits`: credits exhausted or billing guardrail hit.
* `429 Tenant submit/concurrent limit exceeded`: tenant guardrail triggered.
* `404 Job not found`: cross-tenant access attempt.

If a job fails, download the diagnostics artifacts as well. Start with:

* `runner.log`
* `diagnostics.json`
* `user_job.log`
* `command.stderr.log`

See [Artifacts and Diagnostics](./artifacts-and-diagnostics).