# Quickstart

> Run the shipped TUI against your own tools, in shadow mode first. Every transcript in these examples is sample output.

Reading time: 10 min. Source: https://www.voidagent.tech/docs/quickstart

Version 1.0.1. The TUI and the MCP server are shipped. The desktop app is in beta for macOS, Windows and iOS, by application. This guide follows the TUI, which is the surface you run.

Before any of it: Node.js 24 or newer, and a clone of the product repository. VOID is not published to a package registry: the packages inside it are private at version 0.1.0, and you run them from the clone. The handbook that documents the product is maintained with the product and is not published, so this page cannot link you to it and cannot be checked against it either. Where the two disagree, the product is right and this page is a summary written by someone reading it from the outside.

## 1. Choose your surface

```shell
# the local terminal workspace, which is the surface this guide follows
pnpm install --frozen-lockfile
pnpm tui

# the agent application
pnpm gui

# the native desktop app, which carries its own Node and backend
pnpm desktop:setup && pnpm desktop
```

- **TUI** — The live local terminal workspace. Chat, documents, reviewed Undo, signed ledgers and policy all run on real local data. On macOS, VOID.command does the same thing from a double click.
- **Agent application** — The agent application. Connect a provider in Settings and select a model; managed documents and captured Undo work without a separate tool server.
- **Desktop** — The native desktop app. The package carries its own Node and backend. macOS 13.5 or newer.
- Built and shipped. The MCP server, with the VOID tool ready to register with the agents that call tools. Register the MCP server and the VOID tool with the agent that already calls your tools.

> The desktop app is for macOS, Windows and iOS. There is no Linux build, and there is no promise of one.

> The product is 1.0.1. The packages inside its repository are private, at version 0.1.0, and unpublished. The import at the top of this sample names a package inside the product repository, at version 0.1.0, that is private and unpublished. It resolves from a clone of that repository and cannot be installed from a registry, so the sample shows a shape rather than a line you can paste. The product and its documentation are maintained together and are not published, so this page is a summary written from outside them rather than a copy of one.

## 2. Shadow mode

> Shadow mode never blocks a call. It records intent, computes the class and builds the compensation plan, so you get a real picture of your exposure before enforcing anything.

```agent.ts
import { void_ } from "@void/sdk";
import { myTools } from "./tools";

const tools = void_.wrap(myTools, {
  mode: "shadow",                // record only, hold nothing
  policy: "./void.policy.ts",
  ledger: { sink: "file://./ledger", sign: true },
});

export const agent = createAgent({ tools });
```

## 3. Watch a run

```shell
$ void watch --agent billing-ops
  [09:14:02] intent    issue_refund(ch_3P9k, 4200 EUR)
  [09:14:02] preflight blast radius: 1 payment, 1 ledger row, 1 email
  [09:14:02] class     R3  irreversible
  [09:14:02] policy    SHADOW, would have held
  [09:14:03] commit    ok, sealed 0x9f3c..a10e
```

## 4. Read the week one report

After a few days of shadow mode, the report tells you how much irreversible action your agents actually take. That number is what your first real policy is built from.

```shell
$ void report --since 7d
  intercepted        18,422 calls
  reversible (R0/R1) 13,517  73.4%
  mitigable  (R2)     3,908  21.2%
  irreversible (R3)   997  5.4%
  would have held     211 calls across 4 tools
```

## 5. Turn on enforcement

When you are ready, change mode to enforce. Policy holds and vetoes become real, and irreversibility budgets start counting.

```agent.ts
const tools = void_.wrap(myTools, {
  mode: "enforce",
  policy: "./void.policy.ts",
  budget: { irreversible: 2 },
  ledger: { sink: "s3://acme-void-ledger", sign: true },
});
```

## Next

- [Read about the MCP server](/docs/mcp-proxy): if your agent calls tools over MCP.
- [Read the policy language reference](/docs/policy): to write your first rules.
- [Read the ledger format](/docs/ledger): if you need to export for an audit.
- [Read the specification](/spec): for the full event model.

---

This document is the markdown form of https://www.voidagent.tech/docs/quickstart, published for agents that read
text rather than a rendered page. It is generated from the same data the page
renders, so the two cannot disagree.