Dura
Sign in Start your table

Connect your AI agent to Dura

DevelopersUpdated

An AI agent with a Dura token can do what you do on the table: check the balances, record a spend while you're still at the till, share out a cash-in, read a receipt photo and square up IOUs. This guide connects one in three steps and sets the rules it should follow.

What an agent can do

  • Read: the table (every envelope's balance, budget and what's been spent this month), activity, IOUs and month summaries.
  • Record: spends (including spends paid with another envelope's cash), cash-ins with the exchange cost, moves, IOU settlements and cash counts.
  • Receipts: upload a photo or PDF, read the suggested envelope for each line, and confirm it.
  • Fix: change a spend's amount or note, or undo any entry.

It can't see other households, change who's in yours, delete your household or read your password. Every write appears on your partner's phone as it happens, with your name on it, because the agent acts as you.

Step 1: make a token

  1. Sign in to Dura and open Settings, then Your account.
  2. Under Apps and agents, name the token after what will use it, like "Hermes assistant", and choose Create a token.
  3. Copy the token (it starts with dura_). It's shown once.

Store it where your agent reads secrets: an environment variable called DURA_TOKEN, your agent's secret store or a password manager. Don't paste it into a chat.

Step 2: give it the CLI or the API

Agents that run shell commands

Hermes, Claude Code, Codex, Cursor, Aider and most coding agents can run commands. Give them the dura CLI. It's one Ruby file with no dependencies (Ruby 3.2 or newer):

mkdir -p ~/.local/bin
curl -fsSL https://dura.muchiround.com/cli/dura -o ~/.local/bin/dura
chmod +x ~/.local/bin/dura
export DURA_TOKEN=dura_...
dura --json whoami

When it's piped, as it is for an agent, the CLI prints the API's JSON and exits with 1 on an API error and 2 on a usage error, so the agent can tell what happened. See the CLI guide.

Agents and apps that speak HTTP

Custom GPT actions, n8n, Zapier, Make, a Telegram bot or your own code call the API directly:

curl https://dura.muchiround.com/api/v1/me -H "Authorization: Bearer $DURA_TOKEN"

The quickstart records a first spend in five requests, and the API reference covers every endpoint.

Step 3: hand over the instructions

Dura publishes a plain instructions file for agents at https://dura.muchiround.com/developers/agent.md. It covers the setup, every command, and the house rules below. Tell your agent:

Read https://dura.muchiround.com/developers/agent.md and follow it.
My Dura token is in the DURA_TOKEN environment variable.

The file starts with skill front matter (name and description), so agents that keep skills, like Hermes and Claude Code, can save it as one and load it whenever you mention your envelopes.

House rules for agents

  1. Read the table before writing. It has every envelope's id, name and balance. Ask when it isn't clear which envelope something belongs to.
  2. Amounts are in your currency, not cents. 74.99 is seventy-four ninety-nine. Responses carry amount_cents integers and a display string.
  3. One write per real event. Send an idempotency key based on the event (receipt-3f2a-line-4). If the network drops and the agent retries, Dura replays the first answer instead of recording the spend twice.
  4. Report back from the response. Each write returns a one-line summary and the new balances. The agent should quote those, not do its own arithmetic.
  5. Undo, don't delete. Entries can't be deleted. A mistake is undone with a mirror entry and recorded again, so the history always adds up.
  6. Confirm receipts with a person unless you've told the agent it can confirm on its own. Nothing is deducted until a receipt is confirmed.
  7. Savings groups: people decide. An agent never confirms or disputes an entry, accepts a turn swap or the keeper's book, records a write-off or finalises a share-out on its own. It shows you what's waiting and acts only on your answer for that one entry.

Revoking access

Open Apps and agents again and choose Revoke next to the token. The next request with it gets a 401. A CLI can also revoke its own token with dura logout --revoke.

More for developers