Agent access (beta)

Agent access lets you connect your own apps and tools to a kitchen — a command-line tool, a script, or an AI agent — with a token, a secret that lets the app or tool use that one kitchen as you. The Mirepoix iPhone app, once it’s out, isn’t one of them: it connects with a token of its own whether agent access is on or off. This page covers turning it on, creating and revoking tokens, connecting a command-line tool by approving it, and what happens when a token misbehaves.

Agent access is a beta. It’s off for every kitchen until a kitchen owner turns it on.

Turn agent access on

Only kitchen owners see this setting.

Tap mirepoix in the navigation bar, then choose Kitchen Settings.
In the Agent access (beta) section, check Let members connect apps and tools.

It saves the moment you check it. Every member of the kitchen can now create tokens for it.

What a token can do

Each line is one thing an app or tool can ask for. Ten of them make a change: adding a recipe, changing one, adding recipes to the Menu, taking recipes off the Menu, putting items on the shopping list, checking them off, unchecking them, taking them off, changing Pantry items, and saving a page to your Pending Imports.

What it does	Name the app or tool uses	Access it needs
Lists every recipe: title, category, tags, and when it last changed, plus deleted recipes still in Recently deleted	`recipes.list`	Read only
Searches recipes by words in the title, a tag, the category, or an ingredient	`recipes.search`	Read only
Reads one recipe’s whole text, the same recipe as the recipe editor holds it, and the names of its ingredients, and says whether that text, sent back unchanged, would save the same recipe	`recipes.get`	Read only
Checks recipe text, or the recipe as the editor holds it, without saving it: whether it could be added, the title and page address it would get, and any recipe already at that address	`recipes.validate`	Read only
Adds a new recipe from recipe text, or the recipe as the editor holds it, never replacing one that’s already there	`recipes.create`	Read and change
Replaces a recipe’s whole text, or the recipe as the editor holds it, with an edited version, as long as the recipe hasn’t changed since the app or tool read it	`recipes.update`	Read and change
Says what you still need to buy to cook one recipe, and what’s already on hand or on the shopping list	`recipes.shopping_delta`	Read only
Reads what’s on the Menu now, by title	`menu.get`	Read only
Suggests recipes for the Menu: ones often on it but not lately, ones added recently, and quick ones you have everything for, leaving out what’s already on it	`menu.suggest`	Read only
Adds recipes to the Menu, up to 5 at a time, and says which were already on it	`menu.add`	Read and change
Takes recipes off the Menu, up to 5 at a time, and says which weren’t on it	`menu.remove`	Read and change
Reads the shopping list for one store, or every store: each item, its amount as the list shows it, its aisle, and whether it’s checked off	`groceries.list`	Read only
Puts items on the shopping list, each in your own words, and says which were already there	`groceries.add`	Read and change
Checks items off the shopping list	`groceries.check`	Read and change
Unchecks items on the shopping list that were checked off	`groceries.uncheck`	Read and change
Takes items off the shopping list, checked off or not	`groceries.remove`	Read and change
Checks the Pantry: whether the kitchen tracks an ingredient, has it on hand, or has it on the shopping list — or, with no ingredients named, what’s due for a check	`pantry.check`	Read only
Lists the ingredient names your words can be matched against: every ingredient in Mirepoix’s shared catalog with its other names, your kitchen’s own ingredients that aren’t in the catalog, and up to 150 you bought most recently on Groceries, newest first	`ingredients.list`	Read only
Changes Pantry items, named in your own words: you need it, which puts it on the shopping list; you have it, so the Pantry asks again after a length it picks, or in a week if it picks none; or ask about it today	`pantry.update`	Read and change
Saves a recipe page the app or tool has already read to your Pending Imports, to import later	`captures.add`	Read and change

Read only is the lower of the two kinds of access, so a read-and-change token can do everything on this list. For a line that needs Read and change, a read-only token can still ask what the change would do, but it can’t make it. If the kitchen is read-only because its plan has lapsed, every change is refused, whatever the token.

Adding and changing recipes

Both take a whole recipe, written in Mirepoix’s recipe format or in the form the recipe editor holds it, which a read returns. A recipe Mirepoix can’t accept is refused with the reason, and nothing is saved.

Adding never overwrites. If a recipe is already at the page address the new title would get, nothing is saved. Two different titles can share an address, such as ones that differ only in capital letters. The app or tool is told which recipe is there, and whether it’s already exactly this recipe.
A change never saves over a newer one. The app or tool reads the recipe first. If anyone edits the recipe’s text or deletes the recipe after that, the change is refused and nothing is saved. A new title that would give it another recipe’s page address is refused too.
A change replaces the whole recipe. Which ingredient a line means, chosen in the recipe editor, stays with any line that keeps its ingredient name, as it does when you edit the recipe yourself. So does a choice between a line’s substitutes on the shopping list, as long as the line still offers the version you picked; otherwise it starts over at the ingredient written first on the line. A new title renames the recipe the way the editor does, so other recipes that mention it are updated to match, and the app or tool is told which ones.
It shows in the recipe’s history. Each version is saved under your name and marked with the token: via CLI and the token’s name for a token from your Account page or a device you approved, or via Siri for the iPhone app’s token. When a change renames a recipe, the other recipes updated to match carry the same mark. See Recipe history.
The editor’s form saves exactly what was changed. Recipe text can’t write down everything a recipe can hold. Examples are a list or a ## heading inside a step’s instructions, a step with no title after a titled one, or an amount like 3.14159 g. Reading a recipe gives the app or tool both forms, and says when the text would change it. Sent back in the editor’s form, a recipe is saved exactly as the recipe editor saves it, under the same rules. Every line the app or tool kept stays the same line. The ingredient chosen for it and the substitute picked on the shopping list carry over as they do when you edit the recipe yourself. A layout the editor can’t hold is refused rather than saved differently, and so is setting or changing a substitute’s package or second measure. A line can also hold an amount the editor’s form can’t carry exactly. Reading the recipe says so, and sending that line back in the editor’s form is refused rather than saved with a different amount.
No deleting. A token can’t delete a recipe.

An app or tool names each recipe by its page address, or in words such as its title. One request can add or take off up to 5 recipes. It works on recipes only: a QuickBite can’t be added to the Menu or taken off it this way.

A name that could mean more than one recipe, or matches one only loosely, comes back to choose. The app or tool is told which recipes it might mean, so it can ask you.
One recipe it can’t place stops the whole request. If a recipe in the request can’t be found, or can’t be placed for sure, nothing on the Menu changes. That includes the recipes it did find.
Adding reports what’s already there. A recipe already on the Menu is left as it is, and the app or tool is told it was already there.
Taking a recipe off again says it’s off. A recipe that isn’t on the Menu is left as it is, and the app or tool is told it’s off. Sending the same request twice changes nothing the second time.
A recipe deleted in the meantime isn’t added. If a recipe is deleted while a request is adding it, the app or tool is told it’s no longer in your recipes.
It’s the same Menu you see. A recipe added this way is on the Menu for everyone in the kitchen. Its ingredients show on the Pantry, as when you add it yourself. Its weeks on the Menu are remembered the same way too. See Selecting recipes.
The shopping list keeps its items. Changing the Menu doesn’t put anything on the shopping list or take anything off it. Amounts on items already listed follow the Menu, as when you change it yourself.

Changing the shopping list and Pantry

An app or tool names a shopping-list item in your own words or as the list shows it, and a Pantry item in your own words.

Adding reports what’s already there. An item already on the list, and not checked off, is left as it is, and the app or tool is told it was already listed. Adding an item that’s checked off puts it back on the list, unchecked.
Checking off works like tapping an item off on Groceries. The item counts as bought at once, so the Pantry takes it off the list and restarts its clock, though it stays on the shopping list, crossed off, for an hour. Unchecking it within that hour undoes it. See Tap an item off as you shop.
Checking off, unchecking, and taking off act only on what’s listed. A name that isn’t on the list comes back as not found, nothing is added, and nothing else in that request changes either. An item already checked off, or already unchecked, is left as it is.
Taking an item off again says it isn’t there. If the app or tool sends the same request after the item has come off, it’s told the item isn’t on your list, and nothing changes.
Saying you need a Pantry item puts it on the shopping list. If it’s already there and not checked off, it’s left as it is. If it’s there but checked off, it goes back on the list, unchecked. An item set to Don’t ask on the Pantry stays set that way.
Saying you have a Pantry item can take a length. The app or tool can pick when the Pantry asks again: in 3, 7, 14, 28, or 84 days, the lengths under Have it, ask again in… on the Pantry. It works like picking one of those, and takes the item off the shopping list. If it names no length, the Pantry asks again in a week, as when you pick 1 week under Have it.
Saying you have an item set to Don’t ask sets no reminder. The Pantry counts the item as on hand already, so a length, if the app or tool names one, changes nothing. If the item is on the shopping list and not checked off, saying you have it takes it off, as Have it does on that Pantry row. Otherwise nothing is written: an item that’s checked off already counts as bought, and stays checked off. Either way, the app or tool is told the item is set to Don’t ask and counts as on hand: its status is not_asking, with no date for the next ask. The Pantry still doesn’t ask about it.
Asking about a Pantry item today makes it due now. An item on the shopping list comes off it and is due for a check today, whatever its reminder said. Off the list, an item set to be asked about later becomes due today, and one that’s already due, or was never answered, is left as it is. An item set to Don’t ask is asked about again: asking turns back on, and it’s due today.
For a Pantry item, a name Mirepoix doesn’t know is added only by saying you need it. If it isn’t in Mirepoix’s ingredient catalog, your kitchen has no record of it, and your Pantry doesn’t show it, saying you have it or asking about it changes nothing. A recipe that uses it doesn’t count unless the recipe is on your Menu. The app or tool is told Mirepoix doesn’t know the name yet, and that saying you need it adds it.
A Pantry answer already in place changes nothing. If the item is already where the answer would put it, it’s left as it is.
Changes match against your whole list. With a shopping-list change or a Pantry change, an app or tool can ask for one store’s list back, or every store’s. A curated store’s list shows only what you’ve marked available there, so an item a change just touched may not be in it. Which items a change matches doesn’t depend on the store. When it names no store, the list comes back for the store you last picked in the store picker on Groceries.

Saving a page to Pending Imports

An app or tool can save a recipe page for you to import later, the way the import bookmarklet does. The app or tool reads the page itself and sends what it found; Mirepoix doesn’t open the page to save it.

It waits under Pending Imports. The page waits under Pending Imports at the top of your recipes list in the token’s kitchen, beside pages you saved with the bookmarklet, and only you see it there. Open it, and Mirabel asks before importing anything. A page you neither import nor dismiss clears itself after 30 days.
The app or tool is told what happened: whether the page was saved (or, when it only asked, would be) or was already waiting, and its title as it shows under Pending Imports — or, past the daily limit, that the limit has been reached.
Sending it again keeps one entry. If the same page content is sent again within 10 minutes, while the first is still waiting in that kitchen, nothing new is saved, whichever way each was saved — a page you saved with the bookmarklet included.
The daily limit is shared. At most 50 pages from the last 24 hours can wait under Pending Imports at once, counting every way you save them and every kitchen. Past that, saving is refused; import or dismiss some, or try again later.
A page too large to keep is refused. Everything sent for one page has to fit in 64 KB, the same limit every saved page has, and each part has a limit of its own too, such as 40,000 characters of text. Over a limit, nothing is saved.

Tokens

A token belongs to you and one kitchen. Whatever an app or tool does with it, it does as you, in that kitchen only.

Read only or read and change. A read-only token can only read. A read-and-change token can also add and change recipes, add recipes to the Menu and take them off, change the shopping list and the Pantry, and save pages to your Pending Imports, as described above.
Up to 20 per kitchen. You can have up to 20 working tokens in each kitchen. A suspended token doesn’t count toward the 20.
Shown once. Mirepoix shows a token you create on your Account page once, when you create it, and never again. A token for a device you approve goes straight to the device and is never shown to you. Keep it as private as a password: anyone who has it can use your kitchen as you.
Checking what it’s for. An app or tool can ask Mirepoix which kitchen its token is for, its kind and access, and whether it can make changes right now, without changing anything in your kitchen.

Create a token

Before you start: a kitchen owner has turned on agent access for the kitchen. If none of your kitchens has it on yet, the Account page says To create a token, a kitchen owner first turns on Agent access in that kitchen’s Settings.

Tap mirepoix in the navigation bar, then your initials at the top right of the menu, to open your Account page.
Find Agents and devices.
In Kitchen, choose the kitchen. Only kitchens with agent access on are offered.
In Name, type something you’ll recognize later, like “Work laptop”. It can be up to 60 characters.
Under Access, leave Read only selected, or choose Read and change.
Tap Create token.
Tap Copy beside the new token, and paste it into your app or tool.

The token appears in your list under its kitchen, and Mirepoix emails you about it. Once you leave the page, the token can’t be shown again; if you lose it, revoke it and create another.

Connect a command-line tool by approving it

A command-line tool can connect without you copying a token: it asks Mirepoix to connect, and you approve it in a browser. Mirepoix has its own command-line tool that connects this way — see The command-line tool for how to install it. The tool gives you an eight-character code, written as two groups of four like K7QM-3XRD, and the address of the page to type it on.

Before you start: a kitchen owner has turned on agent access for the kitchen you want the tool to use.

In a browser, open the Connect a device page: mirepoix.recipes/device. If you’re signed out, Mirepoix asks you to sign in first and brings you back here afterward, as long as you finish signing in within ten minutes, in the same browser.
In Code, type the code the tool shows, then tap Continue. Capital or small letters both work, and so does leaving out the dash. An O typed for a zero, or an I or L typed for a one, still matches.
On Approve this device?, check that the request is yours. It shows what the device calls itself, the IP address it connected from, the software it reported, and how long ago it asked. A device can call itself anything; the IP address and software are what Mirepoix saw when the request arrived. Approve it only if you started it yourself, just now.
Under Kitchen, choose the kitchen. Only your kitchens with agent access on are listed. If there’s only one, it’s already chosen.
Under Access, leave Read only — it can look things up but can’t change anything selected, or choose Read and change — it can also make changes in this kitchen.
Tap Approve. If you don’t recognize the request, tap Deny instead.

After you approve, the page says Approved. Go back to your device — it will finish connecting in a few seconds. The tool collects its token, and Mirepoix emails you about it. The token appears in your list under its kitchen, named what the device called itself. From then on it’s like a token you created on your Account page: you can revoke it, it counts toward your 20, and it ends the same ways. After you deny, the page says Denied. Nothing was connected.

A code lasts ten minutes. After that, typing it gets the same answer as a mistyped code, below. If the request expires or is answered somewhere else while you’re on Approve this device?, tapping Approve or Deny, or reloading the page, says That request has expired or was already answered. Start again on your device.
A code that doesn’t match gets That code doesn’t match a device waiting to connect. Check it and try again. After too many tries, the page says Too many codes tried. Wait a few minutes, then try again.
No kitchen to choose. If none of your kitchens has agent access on, the page says so and offers only Deny.
Already at 20 tokens. If you have 20 working tokens in the kitchen you chose, approving says You already have 20 tokens for this kitchen. Revoke one before creating another.
Turning agent access off cancels the approval. If a kitchen owner turns agent access off after you approve but before the tool collects its token, the tool doesn’t get one.

The iPhone app’s token

The Mirepoix iPhone app isn’t out yet. Once it is, the app creates its own token while you’re signed in to it, whether the kitchen’s agent access is on or off. There’s nothing to copy or paste.

It’s always read and change.
It shows with the app’s sign-in. On your Account page, the app’s row under Where you’re signed in has a line for each kitchen the app is connected to: Connected to Siri and Shortcuts in, then the kitchen’s name. It isn’t listed under Agents and devices.
It ends with the app’s sign-in. Signing out of the app ends it. So does tapping Sign out on the app’s row under Where you’re signed in, or Sign out of all other sign-ins from another device. It also stops working when that sign-in expires.
The app reconnects by itself. If its token is revoked, suspended, or refused for any other reason, the app gets a new one the next time you open it while signed in.
No email of its own. Signing in to the app is a sign-in like any other: Mirepoix emails you about a sign-in from a device it doesn’t recognize. The token the app gets after that sends no separate email.

To cut off an iPhone for good, sign it out under Where you’re signed in. As long as that sign-in lasts, Mirepoix gives the app a new token whenever it asks for one.

Revoke a token

Your own tokens. On your Account page, under Agents and devices, tap Revoke beside the token and confirm. Whatever uses it stops working right away. Revoke any token you don’t recognize.

Every member’s tokens (owners). In Settings, the Agent access (beta) section lists every member’s tokens for the kitchen in two groups, each headed with how many it holds: Other apps and tools, then iPhone app. A group with no tokens isn’t shown. Each token shows its member’s name, what kind it is, its access, when it was last used, and when it was created. Tap Revoke beside one and confirm to cut it off. The member isn’t emailed about the revoke.

An iPhone app’s token comes back, though. While its member stays signed in, the app gets a new one when it’s opened after Siri has found the old one refused, or once the old one is a day old. Turning agent access off doesn’t cut it off either. To cut off a member’s iPhone for good, remove the member from the kitchen, which deletes all their tokens for it, the iPhone app’s included.

Turn agent access off (owners). Uncheck Let members connect apps and tools. Mirepoix asks first, and the question says how many other apps and tools are connected — “This disconnects 2 apps and tools and deletes their tokens” — or that none are, and that the Mirepoix iPhone app isn’t affected. Turning it off deletes every token under Other apps and tools, suspended ones included, and turning it back on restores none of them. The iPhone app’s tokens stay, suspended ones too, and the app stays connected. Turning it off also cancels any device approved for the kitchen that hasn’t collected its token yet.

If the kitchen is read-only because its plan has lapsed, an owner can still turn agent access off and still revoke single tokens. Turning it back on waits until the plan is active again.

A token also ends on its own:

Unused for 90 days. A token you created on the Account page, or by approving a device, stops working once it’s gone 90 days without being used, and it’s deleted — the next time something presents it, or by Mirepoix’s daily cleanup, whichever comes first. This doesn’t apply to the iPhone app’s token, which ends with its sign-in.
You leave the kitchen, or an owner removes you. Your tokens for it stop working and are deleted, the iPhone app’s included.
The kitchen or your account is deleted. Its tokens go with it.

Automatic suspension

Each token has its own rate limits: up to 120 reads and 30 changes a minute. Asking what a change would do counts as a change, and so does a change that’s refused. A token that goes over its own limits in three separate stretches within a day is suspended automatically, and Mirepoix emails you.

All your tokens in one kitchen also share a budget of 1,200 calls an hour, reads and changes alike, including asking what a change would do. Going over it refuses their requests for the rest of that hour, but it never counts toward suspending a token.

A suspended token can’t be used again. It stays in your list, and in the owners’ list in Settings, with the line Suspended for going over its limits, and its button reads Dismiss in place of Revoke. Tap Dismiss and confirm to clear it. The iPhone app’s suspended token says so on its sign-in’s row instead, and the app replaces it the next time you open it while signed in.

If you still want the app or tool connected, check that it isn’t sending requests in a loop, then create a new token for it.

Emails about tokens

Mirepoix emails you:

When you create a token on your Account page, or a device you approved collects its token. The email names the token, the kitchen, and its access, gives the time, and shows the IP address and browser of the request that created it. For an approved device, that request is the device collecting its token, so the IP and Browser lines show the device’s address and software, not the browser you approved it in. If it wasn’t you, revoke the token on your Account page right away. The iPhone app’s token sends no email of its own.
When a token of yours is suspended. The email names the token, what used it, and the kitchen.

What leaves the app

What an app or tool reads with your token goes wherever you send it — to an AI model you drive a tool with, for example — under that destination’s own terms. That can include recipes and other content your kitchen’s other members wrote. The privacy page’s “Agent access (beta)” section spells out what a token can read and what Mirepoix keeps about each token.