Skip to the guide

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 · Source and releases

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 situationA useful first projectWhat changes
You copy context between sessionsA project handoffThe next session reads current work instead of a pasted transcript.
You switch agents or providersA portable working recordCompatible clients use the same artifacts.
You manage several agentsA shared work queueTasks, owners, outputs and next actions are queryable.
A group brings different agentsA team handoff protocolAgents contribute to the same records.
One agent feeds anotherA reviewed two-step loopOutputs and review gates become explicit state.
Collaborators do not use agentsA review pagePeople act through a view of the same data.
Progress is buried in logsA workflow status viewPeople can see results, blockers and available actions.
Memory has become opaqueAn evidence notebookNotes link to the artifact and decision they explain.
You need to investigate mistakesA change and recovery notebookRecorded versions support review and deliberate correction.
State plumbing dominates an automationA command and ruleInternal transitions live with the work.
Skills are scattered and driftingA versioned skill catalogueAgents find instructions and record the version used.
A prototype needs shared persistenceA small shared applicationA group can contribute through one link.

Choose a starting path

Use the client and service matrix 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:

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 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 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 includes shell execution. Its provider guide 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:

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 records their platforms, release channels and verification status.

Follow the host-specific setup steps 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 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. It defines the schema, one sample record and a minimal view. Later recipes extend this same example:

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:

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 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 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, 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 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. 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 are below. Confirm hosted access before scheduling a real trial: the template does not make early access available by a deadline. The review example 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 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 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 illustrates small software shared with a group.

Try: install the agenda editor. 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: 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.

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:

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:

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:

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:

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:

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:

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:

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

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.