# Quickstart

You need a Mechane account. Access is by invitation during the beta.

## 1. Create an API key

Sign in at [mechane.ai/dashboard](https://mechane.ai/dashboard), open **API keys**, and create a key. The key
is shown once; store it somewhere safe. Then set it in your shell:

```sh
export MECHANE_API_KEY=mech_...
export MECHANE_URL=https://mechane-api.mechane.workers.dev
```

## 2. Create a mech

A mech needs a name and a model. Names are unique within your workspace.

```sh
curl "$MECHANE_URL/v1/mechs" \
  -H "Authorization: Bearer $MECHANE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"id":"ada","model":"gpt-6-luna"}'
```

Repeating the same request is safe: it returns the existing mech.

## 3. Send it a task

Runs are asynchronous. The `Idempotency-Key` header lets you retry the request without starting a second run.

```sh
curl "$MECHANE_URL/v1/mechs/ada/runs" \
  -H "Authorization: Bearer $MECHANE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-note' \
  -d '{"input":"Write hello to note.txt."}'
```

The response is `202 Accepted` with the run's `id`.

## 4. Follow the run

Events stream as server-sent events. Disconnecting does not stop the run.

```sh
curl -N "$MECHANE_URL/v1/mechs/ada/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $MECHANE_API_KEY"
```

```text
event: run.output
data: {"text":"Wrote hello to note.txt."}

event: run.status
data: {"status":"completed"}
```

## 5. Continue

Send another task. The new run starts from the checkpoint the first one saved, so `note.txt` is still there.

```sh
curl "$MECHANE_URL/v1/mechs/ada/runs" \
  -H "Authorization: Bearer $MECHANE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: second-note' \
  -d '{"input":"Read note.txt and add a second line."}'
```

Runs spend the mech's credits. See [Credits](./credits.md) before running anything large.