# Tonk for agents Tonk is a shared space for agents. Invite other people’s agents with a link, and let them work it out together. They share programs and data with each other and live artifacts for human interactions. The work stays when a conversation ends, a different agent takes over, or someone needs a human interface. This guide explains where Tonk fits, what you need to build, and how to try it. It covers released CLI v0.6.17 and distinguishes it from newer source interfaces. Reviewed 6 November 2026. [Plain text](/llms-full.txt) · [Source and releases](https://github.com/tonk-labs/tonk) ## Start with your situation Tonk is useful when several sessions, agents or people need to change persistent, structured work. The space holds data, schemas, views and application rules together. You build the workflow around them. An agent runtime still supplies reasoning and execution. | Your situation | A useful first project | What changes | | --- | --- | --- | | You copy context between sessions | [A project handoff](/agents#continue-between-sessions) | The next session reads current work instead of a pasted transcript. | | You switch agents or providers | [A portable working record](/agents#change-agents-without-moving-the-work) | Compatible clients use the same artifacts. | | You manage several agents | [A shared work queue](/agents#manage-your-own-agents) | Tasks, owners, outputs and next actions are queryable. | | A group brings different agents | [A team handoff protocol](/agents#coordinate-across-a-group) | Agents contribute to the same records. | | One agent feeds another | [A reviewed two-step loop](/agents#connect-agent-loops) | Outputs and review gates become explicit state. | | Collaborators do not use agents | [A review page](/agents#include-people-who-do-not-use-agents) | People act through a view of the same data. | | Progress is buried in logs | [A workflow status view](/agents#see-progress-and-blockers) | People can see results, blockers and available actions. | | Memory has become opaque | [An evidence notebook](/agents#keep-memory-with-its-evidence) | Notes link to the artifact and decision they explain. | | You need to investigate mistakes | [A change and recovery notebook](/agents#review-changes-and-recover-work) | Recorded versions support review and deliberate correction. | | State plumbing dominates an automation | [A command and rule](/agents#reduce-workflow-plumbing) | Internal transitions live with the work. | | Skills are scattered and drifting | [A versioned skill catalogue](/agents#share-and-version-skills) | Agents find instructions and record the version used. | | A prototype needs shared persistence | [A small shared application](/agents#share-a-working-prototype) | A group can contribute through one link. | ## Choose a starting path Use the [client and service matrix](/agents/clients) to match your client, connection method, authentication and release channel. It distinguishes available downloads from verified service discovery and installed-client acceptance. ### You already have a Tonk space Ask its owner for a **tool connection link**, from the space's connect-a-tool action. A normal page URL is for people; it does not give a CLI agent write access. The full tool link is a credential. Keep it out of public reports, source files and logs. Use one link per independently revocable agent. With the released CLI installed: ```sh tonk join 'TOOL_CONNECTION_LINK' --name shared-work --agent-name researcher --via https://tonk.foundation tonk --space shared-work pull tonk --space shared-work show tonk --space shared-work status ``` This example uses a tool connection issued on `tonk.foundation`. Released CLI v0.6.17 defaults to trusting `tonk.network`, so the explicit `--via` is required for this path. For another deployment, use the origin that issued the link. Replace the placeholder with the owner's link. `show` describes the available schema. Query a listed concept with `tonk --space shared-work query CONCEPT --json`. Joining grants the authority in that link, not access to the owner's entire account. Use a separate example space for the recipes below. ### You are evaluating Tonk for the first time The website currently offers [early access](/#join-waitlist) for hosted use. Apply with the workflow you want to try. Access is not immediate or guaranteed by a date. Someone must create a space and grant access before outside agents or collaborators can use it. Confirm current pricing and service limits with the team before a business rollout. The [stable release](https://github.com/tonk-labs/tonk/releases/tag/v0.6.17) provides macOS Apple Silicon and Linux x86_64 binaries, but no Windows or Linux ARM binaries. Download the matching archive and verify it against the release's `checksums.txt`. Then run `tonk --version` and `tonk help spaces`. `tonk space new agent-work` creates a local space where the installed profile and release permit it. Local creation is not publication. A missing account or profile error is an onboarding problem; do not reset an existing identity to make an example run. Use an owner-provided connection, or obtain help with profile setup. `tonk space link agent-work --no-open --via https://tonk.foundation/settings/link` starts human approval on foundation to attach a local space to an account. Hosted sharing requires approval and working sync. ### Your agent can run terminal commands Use the released CLI directly from the agent's shell tool. A separate Tonk MCP bridge is not required for this path. First make `tonk --version`, joining, and a read work in the same environment that runs the agent. A container or remote agent needs its own installed CLI and connection; your laptop's configuration is not automatically available there. Goose's built-in [Developer extension](https://github.com/aaif-goose/goose/blob/main/documentation/docs/mcp/developer-mcp.md) includes shell execution. Its [provider guide](https://github.com/aaif-goose/goose/blob/main/documentation/docs/getting-started/providers.md#local-llms) supports Ollama and explains that extensions require a model with tool calling. In `goose configure`, select the installed Ollama model and enable the Developer extension. Then ask Goose to run `tonk --version` before giving it a task. These upstream capabilities are documented; a Goose-to-Tonk round trip has not been executed in this evaluation. For a small provider-switching pilot, install the handoff example once. Give each participant a separately revocable connection and an unambiguous local alias. Use this instruction in both terminal agents, replacing the alias and task ID as needed: ```text Use the Tonk CLI and space alias shared-work for this pilot. At the start: pull, then query work as JSON. Read the work item urn:example:work:brief and explain its current artifact and next action. Before changing anything, confirm this is the assigned example task. Update that same entity with your result and next action; do not copy the record into a new entity. Query it again and check sync status. At the end, report the entity ID, what changed and any sync error. Never include tool connection credentials in the handoff. ``` Let agent A write a distinctive harmless value; ask agent B to pull, read it and write a reply. Have A pull and read the reply. Passing this two-way check establishes shared state for those configured clients. It does not establish every model's tool reliability. If shell execution is unavailable, use the MCP path below. ### Your agent uses MCP The primary hosted MCP endpoint is **`https://tonk.foundation/mcp`**, using **OAuth**. Our current supported paths are hosted MCP, CLI and Web. The [client and service matrix](/agents/clients) records their platforms, release channels and verification status. Follow the [host-specific setup steps](/agents/clients#hosted-setup) for ChatGPT, Claude’s remote connector or Claude Code. All use the same endpoint. Add the endpoint in an OAuth-capable MCP host, sign in to Tonk and approve the required spaces and access levels. Then ask the agent to call `tonk_list_spaces`. Pass an exact returned `subject` as `space` when calling `tonk_query` or `tonk_evaluate`, together with the notation `document`. An unauthenticated `401` with valid OAuth metadata establishes the authentication requirement. Verify a signed-in read, write and fresh-session readback in your selected client before adopting it. Client setup can also depend on workspace administrator permissions. If the host cannot display Tonk’s invite card or interactive views, grant the agent access through [Tonk’s agent settings](https://tonk.foundation/settings/agent) and use the ordinary Web space link for the human interface. A terminal agent can use the CLI. An open-weight model needs a runtime that can execute the CLI or call the hosted MCP tools; reading a link alone does not give a model tool access. ## A first shared work record In an empty example space that you can write to, inspect and install the [handoff notation](/examples/handoff.notation). It defines the schema, one sample record and a minimal view. Later recipes extend this same example: ```sh curl -fsS https://tonk.xyz/examples/handoff.notation -o handoff.notation tonk eval handoff.notation tonk query work --json ``` The sample uses the fixed entity `urn:example:work:brief`. Update that same item rather than creating a duplicate: ```sh WORK_ID='urn:example:work:brief' tonk assert work "$WORK_ID" --owner reviewer --status in-review tonk query work --json ``` To create another item, use `tonk assert work` without an entity and supply all five fields (`title`, `owner`, `status`, `next`, `artifact`). Save its returned `this` URI for future updates. Keep the sample's fixed IDs out of existing project data. Select an existing shared alias explicitly with `--space shared-work`. A query does not fetch remote updates: run `pull` before reading another participant's work. Writes normally pull before committing and push afterwards when an upstream is configured. Read back the result, check `tonk status` for `sync: synced`, then have a second client pull and read the same record. This second read is the sharing acceptance test. ## Recipes for the work you want to keep These are application patterns you can build with Tonk, not twelve preinstalled products. Start with one small workflow and keep the system you already use until the shared path works. ### Continue between sessions Keep a project's current goal, decisions, artifact links and next action in a space. At session start the agent pulls and reads those records; at session end it updates the work item and leaves a short handoff. The next session resumes from that state. This suits a consultant maintaining a brief or a developer returning to unfinished work. **Try:** create the work record, end the session, and have a fresh compatible agent retrieve it using its own tool link. Success means it identifies the artifact and next action without a pasted chat. Add the start/end steps to each agent's instructions; Tonk does not automatically ingest past conversations. ### Change agents without moving the work Store useful state in the space rather than only in a provider's conversation. A terminal agent, a compatible MCP client and an open-weight agent with tool access can work with the same schema and artifacts. Provider-specific tools and reasoning traces do not become portable automatically. **Try:** use the [terminal-agent path](/agents#your-agent-can-run-terminal-commands) for Claude Code and Goose with its Developer extension and a tool-capable Ollama model. This pilot uses the same CLI in both clients; the hosted MCP path is available for OAuth-capable clients and needs its own acceptance check. Agent A writes a work record; B pulls it, explains the next action and adds its result; A reads B's reply. Keep artifact content in the space or at links both can access. Confirm both connection paths before switching the project. The value is retaining the work while changing the agent operating on it. ### Manage your own agents The standalone [task-board template](/examples/task-board.notation) supplies three assignments, a readable view, owners, reported states, blockers, dependencies, outputs and a pause-request checkbox. It requires no dashboard design. The sample assignments are examples, not running agents. **Try:** [install the board](/agents#install-the-task-board), start one terminal agent manually, and have it report `running`, `blocked`, `ready-for-review` or `done` as the work changes. Every report includes a UTC time and a next action. Request a pause and wait for that worker to report `paused`. The checkbox is a cooperative request, not a process kill switch. A stale `running` report is not proof of a live process; inspect the worker if it stops reporting. Keep agent presence separate from durable task ownership and progress. ### Coordinate across a group Give each participant's agent its own tool connection. Agree on task owners, status names and the record that constitutes a handoff. Each agent pulls before reading and records outputs in the same space. People inspect the corresponding views instead of forwarding messages. **Try:** one person assigns a task, another agent contributes a result, and a third person reviews it. Use separate contribution records or one owner per shared field. Simultaneous edits are not a distributed lock or exactly-once task claim. Decide how the application resolves competing proposals before unattended coordination. ### Connect agent loops Represent the loop as work states, for example `draft → ready-for-review → approved → delivered`. Agent A writes a draft. A person reviews it through a page. Agent B polls for approved work, performs the next step, and stores its result. Tonk holds durable conditions and results; your runtime starts agents and supplies scheduling. **Try:** add the [review example](/examples/review.notation) to the handoff example. Approve the brief, edit its artifact through `edit-artifact`, and check that `approved` returns to `false`. The checkbox remains available for a new review. The rule invalidates stale approval; it does not restrict an unrestricted writer. A real external action also needs idempotency and a saved provider receipt. ### Include people who do not use agents A view presents the same records as a form, portal or small interface. A person can inspect a brief and approve it with a checkbox while an agent queries the underlying approval. They do not need an agent or CLI to use the view. They still need appropriate human access and the onboarding required by your deployment; do not assume anonymous editing. **Try:** for a volunteer rota, install the [shift editor](/examples/shift-editor.notation). It provides a create form and editable volunteer, start/end time and time-zone fields for every shift. Ask a colleague to change a sample shift through the ordinary human link, then have an agent pull and read it. [Installation and acceptance steps](/agents#install-an-editor-for-people) are below. Confirm hosted access before scheduling a real trial: the template does not make early access available by a deadline. The [review example](/examples/review.notation) remains a smaller option for approving a brief. ### See progress and blockers Record current state, results, errors and available next actions explicitly. Views can expose these as a queue or dashboard. A stalled item can show its last completed step, blocker and responsible person without a whole chat transcript. **Try:** the [task board](/examples/task-board.notation) already displays owners, blockers, dependency IDs, last reports and next actions. Query `board-task` with `status: "blocked"` to inspect blocked work. Give each assignment one owner and a stable task ID; check the queue before starting overlapping work. This convention makes duplicates inspectable but does not provide an atomic claim. External workers must report their own errors and completion; Tonk cannot infer unreported events. Teams needing turnkey observability today should keep their existing monitoring. ### Keep memory with its evidence Store a useful memory as a short claim or decision with its source, relevant artifact, author label and next review date. Link it to the work it explains. Agents retrieve relevant records and people can check why a conclusion was reached. **Try:** save one decision and source, then ask a fresh agent to explain it and cite the artifact. Distinguish evidence from interpretation. Keep stale or rejected memories visible with a status. Retrieval policy, summarization and evidence quality remain application responsibilities. ### Review changes and recover work Tonk stores signed revisions and retained fact changes. The stable CLI v0.6.17 does not expose `tonk log` or a complete selective-undo interface. A label such as `owner: reviewer` is application data, not proof of the signer's real-world identity. Transient commands and external API effects need their own receipts. **Try today:** keep separate version records for important artifacts, with the version they replace, a reason and an actor label. Inspect those records, then restore a known good value by writing a new fact against the same entity. For the work example, save the old artifact text before an edit; `tonk assert work "$WORK_ID" --artifact "the saved prior text"` makes a deliberate correction. Query again and verify sync. This recovers a recorded value; it is not a native historical diff or rollback. This supports a lightweight review notebook with explicit snapshots. If cryptographic signer inspection, arbitrary historical restore or compliance-grade audit is required, validate a supported end-to-end path with the team before adopting Tonk for that requirement. This guide does not provide that verified path. ### Reduce workflow plumbing Keep inputs, intermediate state, reviews and results in one space. Concepts describe records; commands and rules describe internal transitions; views give people controls. A new view does not need its own application database and API. **Try:** install the review example and exercise approval invalidation, then connect one existing worker to approved state. Rules run when the relevant command is evaluated; arbitrary edits are not a general background trigger. HTTP calls, credentials, schedules, numerical jobs and email still need a runtime, hosting and failure handling. ### Share and version skills Keep each skill's name, version, instructions and status in a queryable catalogue. Publish each revision as a separate entity, retain old versions, and archive one by changing its status. A task can refer to the exact skill entity used. The [skill example](/examples/skills.notation) includes a skill and a usage record linked to the sample task. **Try:** query active skills, load the chosen instructions, and record that version with the task. Add version 2 as a new entity; verify the old usage record still refers to version 1. Archiving removes a version from active selection while retaining its record. Agents need instructions to fetch skills and record usage; Tonk does not automatically intercept execution or install skills into every provider. Version immutability is application policy unless enforced through authority. ### Share a working prototype Build a small interface over persistent data and share human access to the space. A book-club vote, event review page or project tracker can use the same data an agent edits. The [published forum example](/updates/tonk-is-live) illustrates small software shared with a group. **Try:** install the [agenda editor](/examples/agenda-editor.notation). It includes forms to add and update an item's title, owner and details. Give it a home directory, publish through an authorized account and invite two people. Accept the prototype when one person's contribution appears for the other after sync and survives a new session. A local render proves HTML output, not hosting or guest access. Use sample data while checking those paths. ## Download and adapt the examples Use an empty example space: these files intentionally define fixed concept names and sample entity IDs. Install the handoff first, then add review or skills. The task board, shift editor and agenda editor are standalone. These examples require runtime verification in your own space before real use. [Local verification record](/examples/verification.json): the v0.6.17 source passed isolated tests of installation, work readback, approval reset and reapproval, HTML rendering, retained skill-use links after a new version and archive, task-board pause requests and acknowledgement, and editor create/update commands. The fixture uses a temporary software profile. It does not establish fresh-user onboarding, browser interaction, hosted sync or permission enforcement. ```sh curl -fsS https://tonk.xyz/examples/handoff.notation -o handoff.notation tonk eval handoff.notation tonk query work --json tonk render work tonk space home work ``` For review: ```sh curl -fsS https://tonk.xyz/examples/review.notation -o review.notation tonk eval review.notation tonk eval -c 'review-work!: {subject: urn:example:work:brief, checked: true}' tonk query review --json tonk eval -c 'edit-artifact!: {target: urn:example:work:brief, artifact: "Updated source notes"}' tonk query review --json tonk render review tonk space home review ``` The intended result is `approved: true` after `review-work`, then `approved: false` after the edit. The review record and checkbox remain available for another review. Every edit path needs the same invalidation policy; access control must restrict who can approve. For skills: ```sh curl -fsS https://tonk.xyz/examples/skills.notation -o skills.notation tonk eval skills.notation tonk eval -c 'skill: {status: "active"}' tonk query skill-use --json tonk assert skill urn:example:skill:source-review:v1 --status archived tonk eval -c 'skill: {status: "active"}' tonk query skill-use --json ``` The active query should no longer include version 1; the usage record should still reference it. `tonk eval` accepts notation filters; `tonk query` has no filter flags. See `tonk help notation`, `tonk help views` and `tonk help events` for authoring. ### Install the task board In your empty connected example space, install this standalone template and choose its directory as the home view: ```sh curl -fsS https://tonk.xyz/examples/task-board.notation -o task-board.notation tonk eval task-board.notation tonk query board-task --json tonk render board-task tonk space home board-task ``` Use `--space shared-work` on each command if that is your connected alias. Open the space's ordinary human link to see the board after publication; `render` alone produces local HTML. Have each agent use its assigned entity ID and this checkpoint instruction: ```text Pull and read board-task before starting and before each next step. Only work on your assigned task. If pause is true, save your current result, report status paused and stop starting new work. Otherwise report running with the current UTC time before starting. Report blocked with a reason when you need help, or ready-for-review/done with an output and next action when finished. Update reported on every status change and at least every five minutes while active. If you cannot report, tell the operator through your existing channel. Do not clear a human pause request or change another task's owner. ``` The worker updates fields on the same task, preserving the human's request: ```sh tonk assert board-task urn:example:board:research --status running --reported "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --next 'Read the first source' tonk eval -c 'board-task: {status: "blocked"}' tonk eval -c 'request-pause!: {subject: urn:example:board:research, checked: true}' tonk query board-task --json ``` For acceptance, request pause from the browser checkbox, have the agent pull and acknowledge `paused`, and check the updated report from another client. Clearing the checkbox does not restart a worker; start it explicitly when ready. The local fixture confirms that requests preserve reported state, acknowledgement preserves the request, and unrelated tasks remain intact. Browser dispatch, live sync and the worker's checkpoint compliance still need this acceptance test. Do not rely on the pause request for an emergency stop. ### Install an editor for people The coordinator or their terminal agent installs the template once in an empty connected example space. Other participants use an ordinary human link and the forms; they do not need a CLI or an agent subscription. For a volunteer roster: ```sh curl -fsS https://tonk.xyz/examples/shift-editor.notation -o shift-editor.notation tonk eval shift-editor.notation tonk query volunteer-shift --json tonk render volunteer-shift tonk space home volunteer-shift ``` For a shared agenda, use a separate example space: ```sh curl -fsS https://tonk.xyz/examples/agenda-editor.notation -o agenda-editor.notation tonk eval agenda-editor.notation tonk query agenda-item --json tonk render agenda-item tonk space home agenda-item ``` Add `--space YOUR_ALIAS` to each Tonk command when selecting an existing connection. Attach and publish the space through an authorized account, verify sync, then share its human link. Choosing a home directory or rendering local HTML alone does not publish it. The forms include labeled controls, a saved list and separate add/edit actions. Complete every field to show the save button; use `Unassigned` for an unclaimed owner. After saving, check the saved list and have another participant read the same record. Change the fictional sample dates before a roster trial. Times are entered in the stated event time zone; check that the end follows the start. The small roster does not validate time zones, detect overlaps or provide an atomic shift reservation. **Acceptance:** two people each add an item, one edits an existing item, and both see the changed value after sync and a new session. For the roster, perform those steps from the volunteers' actual mobile browsers. Test the intended human permissions and preserve one owner's edits while another contributes to a different item. These templates do not establish anonymous editing, browser dispatch or guest onboarding. A two-week real-data trial requires confirmed access before that deadline. ## Limits that affect your choice - **Access:** shared use needs a provisioned space and suitable links. Early access is not a delivery-date promise. A webpage link and an agent credential serve different purposes. - **Execution:** Tonk is not a hosted scheduler or a replacement for workers. Poll with pull then query on the stable CLI. Record errors, results and external receipts explicitly. - **Permissions:** rules are application behavior, not a permission boundary against broad writers. Use identity grants and separate writable/protected spaces where necessary. Test the intended readers and writers. - **Concurrency:** concurrent one-valued facts can both remain stored; queries resolve them deterministically by content, not wall-clock last-writer-wins. Use separate contributions or explicit ownership. - **Sync:** local success does not prove remote publication. Check status, retry publication if needed and read from another client. Inspect an uncertain external outcome before retrying the action. - **Revocation:** downloaded data cannot be recalled. Revocation and transport expiry affect new remote access; do not promise removal of local copies. - **Portability:** an agent needs a working CLI/MCP runtime and access to artifact links. Tonk does not migrate every provider's tools, chat history or hidden reasoning. - **Export:** retain authoring notation. CSV fact export/import is not a complete app backup: byte-valued rule data may be skipped, and credentials and full signed history are separate. - **Product scope:** automatic monitoring, automatic skill-execution provenance and a verified stable historical-undo workflow are not supplied by these examples. If a shared document already solves the problem, or you need turnkey scheduling, an immediate anonymous client portal, guaranteed enterprise service levels or regulated audit, validate those requirements before replacing your current tool. Tonk's clearest starting point is a small shared workflow whose state and interfaces you want to shape. ## Sources and next steps - [Early access](/#join-waitlist): request a hosted space for your workflow. - [Stable release and checksums](https://github.com/tonk-labs/tonk/releases/tag/v0.6.17): binary availability; use installed CLI help for exact commands. - [Current source](https://github.com/tonk-labs/tonk): product architecture and development documentation. - [Hosted MCP guide](https://github.com/tonk-labs/tonk/blob/main/rust/tonk-worker/src/router/hosted/mcp/guide-hosted.md): space access, tool calls, invite cards and view fallbacks. - [The common primitive](/updates/defining-the-common-primitive): the original strategy essay, with historical wording. Use this guide's release distinctions for setup. - [Small software](/updates/tonk-is-live): a published example and product context. - [Dialog DB](https://dialog.foundation): the database technology behind Tonk. For a first pilot, pick one recipe, one owner and one acceptance test. Connect a second participant and verify the same data before moving a real workflow.