Quickstart

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

1. Create an API key

Sign in at 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:

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.

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.

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.

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

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.

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 before running anything large.