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

# Quickstart

> Journal an agent's tool calls, then roll them back, in about five minutes.

## 1. Run the demo

```bash theme={null}
git clone https://github.com/multimindlab/reversi && cd reversi
npm install
npm run example
```

An agent creates an order, charges a card, sends an email and tries a tool outside its scope. An operator
reviews the plan and rolls the run back. The email stays in the report as *cannot be undone*.

## 2. Look at the evidence

```bash theme={null}
node packages/cli/dist/main.js verify examples/order-agent/out/ledger.jsonl
```

Open `viewer/index.html` in a browser and choose that file. The chain is verified in your browser.

## 3. Describe your own tools

```yaml tools.yaml theme={null}
- tool: create_order
  effect: reversible
  permission: orders:write
  compensation:
    tool: cancel_order
    argument_map: { order_id: $result.order_id }
- tool: cancel_order
  effect: idempotent
  permission: orders:write
- tool: send_email
  effect: irreversible        # forces human approval
  permission: mail:send
```

```bash theme={null}
reversi validate tools.yaml
```

Or start from a project: `reversi init my-project` writes a config, example manifests, a starter policy and tests, then
`reversi doctor` checks the setup and `reversi test` runs the contract tests and the policy's own tests without touching any
system. `reversi lint` flags unsafe or incomplete manifests (a missing owner, no timeout, a mutating tool with no undo).

## 4. Wrap calls

<CodeGroup>
  ```ts TypeScript theme={null}
  import { SealedScope, loadRegistry, openLocal } from "@multimindlab/reversi";

  const reversi = openLocal("./reversi-data", loadRegistry("./tools.yaml"));
  const run = reversi.startRun({
    actor: "support-agent",
    scope: SealedScope.seal(["orders:write"]),
  });

  const r = await run.call({
    tool: "create_order",
    args: { sku: "BOOK-1" },
    reason: "customer asked to order BOOK-1",
    execute: (args) => shop.createOrder(args),
  });
  if (r.status === "blocked") console.log(r.reasons);
  ```

  ```python Python theme={null}
  from reversi_sdk import ReversiClient, Blocked

  client = ReversiClient("http://127.0.0.1:7421", api_key="…agent key…")
  run = client.start_run(["orders:write"])
  try:
      run.call("create_order", "customer asked to order BOOK-1",
               lambda args: shop.create_order(**args), args={"sku": "BOOK-1"})
  except Blocked as e:
      print(e.reasons)
  ```
</CodeGroup>

## 5. Plan and roll back (operator)

```bash theme={null}
reversi plan  <run_id> -m tools.yaml -d ./reversi-data
reversi rollback <run_id> -m tools.yaml -d ./reversi-data --compensator-cmd "./undo.sh"
```

`undo.sh` receives the compensation call as JSON on stdin; exit code 0 means it was undone.

## 6. Or put the gateway in front of an MCP server

No code changes in the agent: point its MCP client at `reversi-gateway`. You do not need manifests to begin. With none, the
gateway starts in **observe** mode: everything runs and is journaled, nothing is blocked, and a banner on stderr lists which
upstream tools are unclassified.

```bash theme={null}
reversi gateway --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server
```

Draft manifests from what the server actually offers, review them, approve them, then enforce:

```bash theme={null}
reversi suggest-manifest --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server -o drafts
reversi manifests publish drafts --registry ./registry --by bob          # drafts are not enforceable yet
reversi manifests approve my.tool --registry ./registry --by alice --four-eyes
reversi gateway --manifests ./registry --upstream-cmd npx --upstream-arg -y --upstream-arg my-mcp-server
```

Look at what happened in a browser with `reversi console` (open mode, your machine only). The [gateway guide](/gateway) covers
modes, schema checks, approvals and rollback; [GitOps](/operations/gitops) covers keeping all of this in git.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.