# Tonk

> A data space you read and write through a link. Agents work with structured data; people use interactive views of that same data. The space holds its data, schemas, views, rules, and signed history, and syncs changes between replicas.

Build a tool, an automation, or a working model in a space, then share access through a link. A person opens a page they can use. An agent connects, queries the data it needs, and writes changes back. You can add a new view or change the application without moving the data into another service.

## What you can do with it

**Keep an automation's state in one place.** Store inputs, intermediate results, assignments, approvals, and outcomes in the same space. People see the flow through a page; agents query and update it directly. Your existing workers call Linear, Slack, email, or other external systems and record the results. You can evolve the flow by changing its schemas, views, and rules.

**Share and adapt an automation.** Publish the app's authoring documents and integration source alongside the space. Another team installs the schemas, views, and rules in its own space, supplies its own credentials, and runs the external workers on its chosen host. For the CLI path, install the notation with `tonk eval`; transfer selected records separately if needed. Stable CSV import can skip byte-valued rule data, so CSV alone is not a complete runnable-app package. Test the copied app's behavior before sharing it.

**Replace a SaaS tool with software shaped around your work.** Build an issue tracker, a project workspace, or an internal knowledge tool over data you control. Give the team views for its own workflow and let agents change the same records. Tonk supplies shared storage, sync, identity-based access, and view rendering; you define the application. Tonk's team describes replacing its Notion and Linear use in the blog. This is a way to build your own tool, with its own upkeep and integration needs.

**Make small software for people you know.** A lunch vote for the team, a shared audiobook catalogue, a discussion space for an event, or a playful collaborative instrument can be data and views in a space. An agent builds the interface; you share it for people to use and change together. The blog shows a forum and reports beta examples including a modular synth and collective fortune-telling spaces. Each new tool can extend a space rather than require a separate application database and API.

**Give agents shared tools and protocols they can evolve.** Put work items, outputs, relationships, and protocol definitions where several agents can query and update them. A new rule, concept, or view becomes available to other replicas after sync. People can inspect and steer the same work through views. Choose the coordination policy in the application: ownership, review, and handling of competing proposals. Shared memory across sessions is one instance of this broader use.

**Work offline and reconnect later.** Field observations or device state can live in local replicas while connectivity is absent, then sync into a shared space. Give people or a compatible device client the data and views they need locally. Choose how the application interprets concurrent updates. The sync primitive is useful here; device adapters, deployment, and any local-network transport still need to be supplied for the hardware and environment you use.

**Build an interactive research model.** Store evidence, claims, assumptions, and their relations as queryable data. Agents can add evidence while people explore the same model through a graph, table, or scenario view. External programs run calculations and write results back. As questions change, define new concepts over the existing facts. The Carry blog demonstrates this style of work with Bayesian networks and scenario models; Tonk brings shared views and links to the same kind of evolving data.

## How the pieces fit

- **Facts** hold the data. Changes append signed revisions; stored history retains earlier values and the authority that wrote them.
- **Concepts** select related attributes into the shape a reader needs. Several concepts can read the same underlying facts. Adding structure does not rewrite those facts, though readers and rules may need updates.
- **Views** are stored with the data. HTML, CSS, and client-side JavaScript give people interfaces for reading and changing it. A page control posts a command; a rule can turn that command into a durable change.
- **Rules** express application behavior. For example, an edit can clear approval, a vote can change a derived status, or a review can publish accepted work. Rules run when their commands are evaluated. You choose the policy and the identities allowed to write; there is no fixed approval workflow you must adopt.
- **Links and replicas** make the space shareable. A link carries delegated access; a client works on a local copy and syncs with other replicas. People and tools use the appropriate share or connection link for the same space.

## Access and first use

Local use needs no account. Hosted sharing needs a Tonk account; beta use is free and access is through the waitlist at https://tonk.xyz. If your operator already has a space, ask for its **tool connection link** and join without a separate agent account:

    tonk join 'TOOL_CONNECTION_LINK' --name my-space --agent-name builder
    tonk --space my-space pull
    tonk --space my-space show

Copy that link from the app's **connect a tool** action. A normal page URL or a person invitation is not a substitute for a tool credential. Joining does not give the agent the operator's whole account. Use a separate link for each independently revocable agent. Treat the full link as a secret.

To start locally:

    curl -fsSL https://github.com/tonk-labs/tonk/releases/latest/download/install.sh | sh
    tonk space new scratch
    tonk concept add task --field title:text:one --field done:boolean:one
    tonk assert task --title "Plan the next session" --done false
    tonk query task --json

`assert` prints the entity's `this` URI. Set `ID` to that URI, then:

    tonk assert task "$ID" --done true
    tonk eval -c 'task:
      done: true'                           # read only tasks with done: true
    tonk assert task "$ID" --done false     # undo by writing a new fact
    tonk query task --json

`tonk space new` selects the space in this directory. Elsewhere, select with `--space <name>`, `TONK_SPACE`, or a directory binding from `tonk space use <name>`, in that order. A query does not pull: run `tonk pull` first when you need remote updates. Writes pull before committing and push afterwards when an upstream is configured. Read back your write and check `tonk status` for `sync: synced` before claiming that teammates can see it.

To attach this local space to an account, `tonk space link scratch --no-open` prints a human approval URL. This needs beta account access. Local creation alone does not publish the space.

## Give the data a page

A concept names the fields you want to read together. Entities that have those fields match it. `tonk concept add` creates attribute names for you; in a hand-written notation document, `the:` names an attribute globally as `domain/name`.

Save this as `task.yaml` and run `tonk eval task.yaml`:

    command!: &toggle-task
      with:
        subject: { description: The task tapped, the: xyz.example.task.toggle/subject, as: entity }
        checked: { description: The new checkbox state, the: xyz.example.task.toggle/checked, as: boolean }
    rule!:
      assert!: task
      when:
        - assert: toggle-task
          where: { subject: ?this, checked: ?done }
        - assert: task
          where: { this: ?this, title: ?title }
    view!:
      this: task
      show:
        ui: '<label><input type="checkbox" checked={done} on:toggle=toggle-task> {title}</label>'
        directory: '<section><h2>Tasks</h2><tonk-display model=task view=ui></tonk-display></section>'

Run `tonk space home task`. Once the space is shared, its home shows the task list. A checkbox tap posts `toggle-task`; the rule writes the matching task's `done` field. The change syncs to other replicas. The command is transient; the durable fact change and signed revision are retained.

You can exercise that command from the CLI too:

    tonk eval -c "toggle-task!: {subject: $ID, checked: true}"
    tonk query task --json
    tonk render "$ID@task!ui"

`render` prints HTML. The route is `entity@model!view`; `tonk render task` prints the directory. Rules bind fields through same-named variables such as `?this` and `?done`. They run when their command is evaluated, not as hosted background workers. See `tonk help notation`, `tonk help views`, and `tonk help events` for authoring.

## Application behavior and authority

Decide which actions matter to your application and express them as commands and rules. An email app can keep content in `draft` and approval in `reviewed`; its edit command changes the content and retracts the old approval. A voting app can have its own rules instead. Examples, including shared agent handoffs and a locally tested approval-reset rule, are in https://tonk.xyz/llms-full.txt.

Access permissions enforce who can write. You can let an agent build under your DID, then end that authority and give it read access for operation. A continuing proposal writer can use a writable space while a human publishes accepted content in a protected space. A rule does not limit a key that retains unrestricted write access. Choose identity grants and application behavior together.

## Execution, sync, and current limits

- Views run in clients. External workers run schedules, HTTP calls, email, numerical calculations, and other background effects. They can run on your laptop, CI, a VPS, or your existing agent runtime. The relay syncs data; it is not a general hosted job runner.
- A local write remains saved if publication fails. Check `tonk status` and retry with `tonk push`. Confirm `sync: synced` before assuming another client can read it. Offline changes reach others after sync.
- If two writers change the same one-valued attribute while apart, both facts remain stored. A query selects one by a deterministic content-hash tiebreak, not by time. Do not rely on last-writer-wins. Use separate contributions, one writer for a shared field, or an explicit application policy.
- History already retains signed revisions and fact changes. Inspection with `tonk log` is implemented in development; stable v0.6.17 does not expose that command yet. Transient commands and outside API actions are distinct from stored changes; retain provider receipts when you need them.
- Revocation stops new remote access as it propagates. Previously issued transport access may last up to one hour, and downloaded data remains local. Tool links are secrets; the current CLI takes them as arguments. Use a separate link for each independently revocable tool and keep credentials out of code repos and logs.
- `tonk query` has no filter flags; filter through notation in `tonk eval` or in code. Stable v0.6.17 has no watch command; poll with pull then query. On ephemeral CI, join each run or retain the private data directory.
- `tonk export --out data.csv` exports branch facts; `tonk import data.csv` reads compatible rows. Stable import can report skipped byte-valued rows, including rules. For a reusable app, keep the authoring notation, install it with `tonk eval`, and transfer only the intended data and assets. CSV alone does not preserve a complete runnable app, credentials, or full signed revision history.
- Public MCP setup is coming soon. Source adapters and current contracts: https://github.com/tonk-labs/tonk/blob/main/mcp/AGENT-LINKS.md. The walkthrough above uses the CLI.
- Stable CLI v0.6.17: macOS on Apple Silicon and Linux x86_64. No Windows or arm64 Linux binary. MIT licensed; built on Dialog DB. Relay source is available, but a complete self-host deployment/recovery guide is not supplied here. Beta is free; this page specifies no paid prices or numerical service limits.

## Links and examples

- Website and beta access: https://tonk.xyz
- Source and releases: https://github.com/tonk-labs/tonk
- Full mechanics and worked examples: https://tonk.xyz/llms-full.txt
- The common primitive and use cases: https://tonk.xyz/updates/defining-the-common-primitive
- Small software and shared spaces: https://tonk.xyz/updates/tonk-is-live
- Interactive knowledge models: https://tonk.xyz/updates/representing-thought-in-carry
- Dialog DB: https://dialog.foundation