<!-- https://mechane.ai/docs/index.md -->

# Overview

Mechane runs persistent agents over HTTP. Each agent is a **mech**: it has its own files, its own
conversation history, and a fixed model. You send a mech a task; Mechane starts a fresh sandbox, restores
the mech's last checkpoint, runs the task, and saves a new checkpoint when it finishes.

Mechane is in private beta. Workspace owners sign in at [mechane.ai/dashboard](https://mechane.ai/dashboard)
to create API keys and add credits.

## Start here

- [Quickstart](./quickstart.md): create a key, create a mech, and run a task.
- [Mechs](./mechs.md): profiles, settings, files, and checkpoints.
- [Runs](./runs.md): submitting work, following events, and cancelling.
- [Workspaces and keys](./workspaces.md): who owns what, and how keys work.
- [Credits](./credits.md): how compute is paid for.
- [API reference](./api.md): every endpoint in one table.

## For agents

Every page is also available as Markdown: add `.md` to its address. The index at
[/llms.txt](https://mechane.ai/llms.txt) lists them, and [/llms-full.txt](https://mechane.ai/llms-full.txt)
contains all of them in one file.

<!-- https://mechane.ai/docs/quickstart.md -->

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

<!-- https://mechane.ai/docs/mechs.md -->

# Mechs

A mech is a persistent agent that belongs to one workspace. Compute exists only while one of its runs is
active; between runs, a mech is its saved checkpoint.

## Names

Names contain lowercase letters, numbers, `_`, and `-`. They start with a letter or number and are at most
64 characters. A name is unique within its workspace.

## Profile and settings

A mech's **profile** is fixed when it is created: the model and the harness that drives it. The current
harness is Codex 0.156.0. Changing the model is rejected; create another mech instead.

**Settings** can change: `instructions` and `reasoningEffort`. Update the defaults with
`PATCH /v1/mechs/{id}`, or override them for one run in the run request. Changing defaults never alters a
run that has already been accepted.

GPT-6 Luna accepts `none`, `low`, `medium`, `high`, `xhigh`, and `max` effort. An unspecified effort means
`medium`.

## Checkpoints

A checkpoint holds the mech's conversation and its files, up to 16 MiB and 10,000 files. A run that
completes saves a new checkpoint before it reports `completed`. A run that fails or is cancelled keeps the
previous checkpoint, so the next run starts from the last good state.

Actions a mech takes outside its sandbox, such as calling another service, are not undone by a failed run.

## Limits

| Limit           | Value                   |
| --------------- | ----------------------- |
| Runs per mech   | One at a time, no queue |
| Run deadline    | 15 minutes              |
| Checkpoint size | 16 MiB, 10,000 files    |
| Name length     | 64 characters           |

<!-- https://mechane.ai/docs/runs.md -->

# Runs

A run is one task given to a mech. Each run gets a fresh sandbox that starts from the mech's latest
checkpoint.

## Submitting

`POST /v1/mechs/{id}/runs` with `{ "input": "..." }` and an `Idempotency-Key` header. The response is `202`
with the run. Optional `settings` override the mech's `instructions` and `reasoningEffort` for this run
only.

A mech runs one task at a time. Submitting while a run is active returns `409`. Reusing an idempotency key
with different input or settings also returns `409`; reusing it with the same request returns the original
run.

## Statuses

| Status       | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `queued`     | Accepted; checking credits and preparing the sandbox.   |
| `running`    | The mech is working.                                    |
| `cancelling` | Cancellation was requested; the sandbox is stopping.    |
| `completed`  | Finished, and the new checkpoint is saved.              |
| `failed`     | Stopped with an error; the previous checkpoint is kept. |
| `cancelled`  | Stopped on request; the previous checkpoint is kept.    |

If the mech does not have enough credits, the run fails with an error that says so. Add credits and submit
again.

## Events

`GET /v1/mechs/{id}/runs/{runId}/events` streams server-sent events:

- `run.status` carries `{ "status": ... }`.
- `run.output` carries `{ "text": ... }`, the full output observed so far.

Each event has an `id`. To resume after a disconnect, send `Last-Event-ID`, or pass `?after=<id>`. Events
are replayed from that point. Disconnecting never cancels a run.

## Reading and cancelling

`GET /v1/mechs/{id}/runs/{runId}` returns the run's status, output, profile, resolved settings, and the
checkpoint it started from. `POST /v1/mechs/{id}/runs/{runId}/cancel` requests cancellation; repeating it is
safe.

<!-- https://mechane.ai/docs/workspaces.md -->

# Workspaces and keys

Every mech belongs to a workspace. When you first sign in, Mechane creates a personal workspace for you
and asks you to choose its URL: your dashboard lives at `mechane.ai/<workspace>/`.

## Workspace URLs

A workspace has a **name**, for display, and a **URL**, its slug. URLs use 3 to 39 lowercase letters,
numbers, and single hyphens, and include at least one letter. Some names are reserved for Mechane's own
pages.

Change the URL at `mechane.ai/<workspace>/settings`. Earlier URLs keep redirecting to the current one,
and nobody else can take them. Release an earlier URL there to let it go: its links stop working and
anyone can claim it.

## Mech pages

Each mech has a page at `mechane.ai/<workspace>/mechs/<mech>`, and the workspace's mechs are listed at
`mechane.ai/<workspace>/mechs`. Mech names are unique within a workspace, so they are not reserved
across Mechane.

## API keys

API keys authenticate requests to the Mechane API. Send one as `Authorization: Bearer <key>`.

- A key can use every mech in its workspace, and nothing outside it.
- A key is shown once, when you create it. Mechane stores only a digest.
- Keys cannot manage users, other keys, or credits; those need a signed-in owner.

Create and revoke keys at `mechane.ai/<workspace>/keys`. Revoking a key blocks new requests immediately.
Runs it already started continue, and open event streams stay open.

<!-- https://mechane.ai/docs/credits.md -->

# Credits

Each mech has its own prepaid balance in USD. Runs spend the balance of the mech they run on: model tokens
at published rates, plus active sandbox time metered per second. Current rates are on the
[pricing page](https://mechane.ai/pricing).

## Adding credits

Workspace owners add credits at `mechane.ai/<workspace>/credits`: choose the mech, enter an amount, and pay
with Stripe Checkout. Credits appear once Stripe confirms the payment, usually within a minute. Credits do
not expire.

## While a run is active

A run reserves part of the balance while it works and settles what it used when it finishes. There is no
per-run dollar cap by default. Credits added during a run are available to the next run.

Automatic reload is not available in this beta.

The full terms are in the [credit terms](https://mechane.ai/terms).

<!-- https://mechane.ai/docs/api.md -->

# API reference

The API is at `https://mechane-api.mechane.workers.dev`. Every request needs
`Authorization: Bearer <workspace-key>`. Bodies are JSON; unknown properties are rejected. Errors are JSON
objects with an `error` message.

| Method | Path                                 | Does                                                                          |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------- |
| POST   | `/v1/mechs`                          | Create `{ id, model, instructions?, reasoningEffort? }`. Safe to retry.       |
| GET    | `/v1/mechs?after=<id>`               | List up to 100 mechs as `{ items: [{ id }], next }`.                          |
| GET    | `/v1/mechs/{id}`                     | Read the profile, settings, current run, and checkpoint reference.            |
| PATCH  | `/v1/mechs/{id}`                     | Update `{ instructions?, reasoningEffort? }` for future runs.                 |
| POST   | `/v1/mechs/{id}/runs`                | Start `{ input, settings? }` with an `Idempotency-Key` header. Returns `202`. |
| GET    | `/v1/mechs/{id}/runs/{runId}`        | Read the run's status, output, and resolved settings.                         |
| GET    | `/v1/mechs/{id}/runs/{runId}/events` | Stream events. Resume with `Last-Event-ID` or `?after=<id>`.                  |
| POST   | `/v1/mechs/{id}/runs/{runId}/cancel` | Request cancellation. Safe to repeat.                                         |
| GET    | `/v1/mechs/{id}/credits`             | Read the mech's balance.                                                      |
| GET    | `/v1/mechs/{id}/usage`               | List the mech's recent usage.                                                 |

## Status codes

| Code  | Meaning                                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------------------------------- |
| `202` | The run was accepted.                                                                                                  |
| `400` | The request body or parameters are invalid.                                                                            |
| `401` | The key is missing, unknown, or revoked.                                                                               |
| `404` | No mech or run with that name in this workspace.                                                                       |
| `409` | The mech is busy, the name exists with a different profile, or an idempotency key was reused with a different request. |