# Using Dux (for agents)

Dux is a sync stack: apps write SQLite on the device, changes reach PostgreSQL, and every row version lands in a lake you query with DuckDB. Version 0.1.0, pre-release, M1 in progress.

## Install

```sh
npm create dux-app my-app
cd my-app && npm install
dux dev
```

## Minimal client

```tsx
import { DuxClient } from "@dux/client";
import { createWebEngine } from "@dux/client/web";
import { DuxProvider, useQuery, useWrite } from "@dux/client/react";

const engine = await createWebEngine({ registry, account: "acme/alice" });
const client = new DuxClient({ engine, url: "wss://sync.example.com/sync", token: getToken });
client.start();
```

## Commands and options

| Command | What it does |
|---|---|
| `dux dev` | Local PostgreSQL, sync server, lake and inspector on free ports |
| `dux dev --no-postgres` | Streams, rollups and `/query` over the lake alone, no sync |
| `dux sql "…"` | DuckDB over the lake, including unflushed stream rows |
| `dux deploy` | Bundle, validate and activate `compute/` |
| `--pg-listen` | Serve the Postgres wire protocol for psql and Grafana |

## Mistakes that break it

1. A stream table without a `write <stream> insert: <predicate>` rule refuses every append.
2. Stream dedupe needs an increasing `seq` per `(tenant, source, stream)`; going backwards loses rows.
3. `dux serve` without `--database-url` serves streams and `/query` only, and needs `--lake`.

## More

- [llms.txt](https://dux.sh/llms.txt)
- [Reference](https://dux.sh/reference)
- [Repository](https://github.com/TimMikeladze/dux)