TUNC.AI / Tunc Orb guides

Keep agent state in the cloud, not in a local JSON file

Checkpoints, processed-item lists and run logs that survive a new session, a new computer or a crashed agent, with retries that never apply twice.

Updated 2026-10-24

Agents that work for more than one session keep state: which items are done, where a long job stopped, what happened on each run. Usually that is a state.json next to the agent. It is lost with the machine, other agents cannot see it, and two runs overwrite each other. Tunc Orb keeps the same state in the cloud, with rules that make concurrent and retried writes safe.

Records for current state

A record holds one value: JSON, text or binary, up to 16 MiB. Create it once, then change it against the revision you last read. A stale revision is refused with revision_conflict, so two agents never silently overwrite each other: the loser rereads and decides again.

curl -s https://api.tuncorb.com/v1/write \
  -H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
  -d '{"operation":"create","name":"jobs/import/checkpoint",
       "about":"Where the nightly import stopped",
       "value":{"cursor":"2026-10-23T00:00:00Z","done":[]},
       "mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'

To change part of a JSON record, send a JSON Patch (add, remove, replace, test). If any operation fails, nothing changes:

curl -s https://api.tuncorb.com/v1/write \
  -H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
  -d '{"operation":"patch","name":"jobs/import/checkpoint","if_revision":"rev_…",
       "patch":[{"op":"replace","path":"/cursor","value":"2026-10-24T00:00:00Z"},
                {"op":"add","path":"/done/-","value":"batch-17"}],
       "mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'

Logs for what happened

A log is append-only: each append adds 1 to 100 entries (up to 64 KiB) and the service assigns their IDs and order. Give an entry an event_key, such as the source message ID, and sending it again returns the original entry instead of a duplicate.

curl -s https://api.tuncorb.com/v1/write \
  -H "Authorization: Bearer $TUNC_API_KEY" -H "Content-Type: application/json" \
  -d '{"operation":"append","name":"jobs/import/runs","about":"One entry per nightly import run",
       "entries":[{"value":{"rows":1204,"status":"ok"},"event_key":"run-2026-10-24"}],
       "mutation_id":"mut_<26 lowercase base32 characters, new for each change>"}'

Retries never apply twice

Every change carries a mutation_id. If a request times out and you do not know whether it landed, send it again with the same mutation_id, or ask for its outcome with data_read operation status. The change is applied once.

From your own code

Create an API key at https://tunchub.com/account/keys/new and send it as a Bearer token to https://api.tuncorb.com (POST /v1/read, /v1/write, /v1/delete). Agents in claude.ai, ChatGPT, Claude Code, Cursor and VS Code use the same store through https://mcp.tuncorb.com/mcp, so a script and an agent can share one checkpoint.

Over remote MCP a single value is at most 64 KiB; keep larger files in Tunc Art and store their artifact_id in a record.
Per agent each second: 50 reads, 20 saves, 5 searches. Short bursts are fine.
Free: 1 GB of storage shared by Tunc Hub, Tunc Art and Tunc Orb, with 50,000 Tunc Orb operations a day.